Che cosa è una buona regola empirica per fare una scrittura tecnica che non confonda le persone

Il mio problema con la scrittura tecnica è sempre stato quello di aver raccolto e imparato molte più informazioni sulla produzione di un progetto, pezzo di codice, qualunque cosa fosse necessaria per la documentazione tecnica. La regola empirica che ha funzionato per me, era di fare una "discarica cerebrale" di tutte le informazioni che avevo. Quindi, prima di ogni altra cosa (prima di strutturare, grammatica, ortografia, qualsiasi cosa) modificherei il documento per rimuovere un terzo del testo senza perdere il significato. (Questa cifra ha funzionato per me - YMMV). Quindi inizierei a esaminare la struttura e la forma della documentazione, introducendo, se necessario, precedenti esempi di struttura rilevanti; o documenti standard che fornivano strutture utili a ciò che stavo cercando di ottenere.

Una volta che il documento era stato inserito in una prima bozza approssimativa tramite il processo sopra descritto, e mediante controlli ortografici e grammaticali, avrei quindi messo da parte il documento per almeno tre giorni. Quindi avrei iniziato il processo di revisione leggendo - lentamente - ciò che avevo già prodotto.

L'editing esterno, la revisione, la lettura o una combinazione di questi è essenziale. In particolare, con la scrittura tecnica, ho riscontrato che non sono assolutamente in grado di giudicare se ho "colpito il punto debole" o meno senza un input esterno.

Supponendo che la tua documentazione tecnica sia per lavoro, puoi sempre chiedere a un collega di correggere le bozze. Molto più facile che cercare di immaginare se sei andato fuori bordo o no.

Non c'è un proiettile d'argento. È come chiedere "Come fai a sapere se il tuo software è privo di errori?". L'unica risposta è: non lo è. Lo stesso vale per la scrittura tecnica (e per tutti i tipi di scrittura): il tuo testo confonderà alcune persone. L'unico modo per dire se qualcuno è confuso da un documento è di fargli leggere.

L'importante è che ti interessi di come le persone leggono e qual è il loro background. Un determinato documento dovrebbe essere indirizzato a un pubblico. E dovresti cercare di ottenere tutto il feedback che puoi. Con l'esperienza dovresti essere in grado di metterti più facilmente nei panni di qualcun altro.

Alla fine scrivere buoni documenti tecnici è ampio e complesso come scrivere un buon codice. Ricorda che il miglior scienziato là fuori è quello che è in grado di spiegare una cosa in un libro o in tv qualcosa che ha richiesto 20 anni per essere scoperto. Quindi ti suggerisco di seguire il suggerimento di Yannis e di porre la tua domanda su scrittori perché potrebbero aiutarti a chiedere di più domanda specifica.