Come programmatore, la scrittura tecnica è un'abilità importante per me. Mi diverto molto. Ho anche imparato da buoni articoli e libri tecnici. Quello di cui ho bisogno sono i principi di scrittura tecnica o le regole per rinfrescarmi la mente.
Qualsiasi articolo pertinente, tutorial e presentazione sono i benvenuti, e anche la tua esperienza sarà fantastica!
La prima regola di scrittura:
Il secondo è relativo:
Probabilmente la parte più difficile che ho trovato con la scrittura tecnica è capire cosa non includere. Hai bisogno di avvicinare i tuoi ascoltatori al tuo punto di comprensione di ciò che fai, ma è così facile impantanarsi in dettagli che non sono importanti. Se il tuo revisore è perso, inizieranno a farti molte domande mirate. Sono davvero utili per aiutarti a determinare cosa è importante e cosa no.
Questo è uno dei migliori consigli che ho trovato:
State your message in one sentence. That is your title. Write one paragraph justifying the message. That is your abstract. Circle each phrase in the abstract that needs clarification or more context. Write a paragraph or two for each such phrase. That is the body of your report. Identify each sentence in the body that needs clarification and write a paragraph or two in the appendix. Include your contact information for readers who require further detail.
- William A. Wood, 8 settembre 2005 ( fonte )
Scrivi in frasi brevi semplici.
Non dare per scontato nulla, spiega tutto. I lettori potrebbero non sapere quale TDD è lo sviluppo basato sui test. Scrivi la prima volta che lo usi.
Modifica la tua scrittura. Dopo averlo scritto, mettilo da parte per diverse ore o giorni, poi leggilo. Troverete molti errori ed errori. Aggiustali. Ora prendi qualcun altro per leggerlo, troveranno di più.
Usa grafica. Un'immagine vale più di mille parole. Le catture dello schermo possono essere incollate praticamente su qualsiasi documento.
Vai passo dopo passo. Durante la preimpostazione di un'attività, elencare ogni singolo passaggio. Non limitarti a dire "apri il file", scomprilo, "apri un file facendo clic su FILE nel menu e poi su OPEN". I lettori esperti salteranno sui dettagli che conoscono, ma con i lettori inesperti saranno dettagliati.
'Considerare il pubblico' è il principale. Non si vuole parlare di un po 'di ribaltamento quando si scrive per i manager, o si spiegano le basi per l'ubergeek residente. Nessuno dei due ne ricaverà nulla e penseranno entrambi che stai perdendo il loro tempo.
In primo luogo, impara a scrivere in modo chiaro e conciso. In ordine di importanza, la scrittura tecnica dovrebbe essere:
Se fallisci # 1, perdi il tuo pubblico.
Devi anche fare un'analisi del pubblico. Scrivere per uno sviluppatore esperto è molto diverso da quello per uno sviluppatore principiante.
I documenti tecnici sono in genere scritti nell'ordine inverso in cui gli utenti li leggono. Per prima cosa scrivi la sezione di riferimento, poi qualsiasi guida / how-to e infine un tutorial.
Se possibile, trova un buon editor per esaminare il tuo lavoro. Si concentreranno sulla parte scritta.
Non aver paura di usare un tono di conversazione. Leggi i tuoi passi ad alta voce. Scoprirai spesso frasi truccate o ottuse che devono essere riviste. Usa la voce attiva. Ciò significa evitare dichiarazioni come "Dopo che il file è stato caricato, ..." Personalmente non mi piace il tempo futuro che vedo spesso nei documenti tecnici, come "Questo metodo ...". Quando? Qualche tempo prima che il sole imploda in una stella rossa?
Potresti prendere in considerazione un corso serale / fine settimana in un college della comunità locale. Come dicevo quando stavo documentando il manuale del programmatore Unix, i primi 10 anni sono i più difficili, LOL.
L'iterazione funziona anche nella scrittura di documenti tecnici mentre funziona nello sviluppo di software. Assicurati di lucidare il documento tecnico ripetendo più volte nella bozza iniziale.
C'è un sacco di buoni consigli qui. Per gettare un altro bocconcino, quando lavoravo in IBM come scrittore tecnico su VisualAge per Java (stavo facendo lo stesso sviluppo della scrittura in quel momento, e successivamente sono tornato allo sviluppo a tempo pieno), abbiamo suddiviso le informazioni in tre elementi di base gruppi:
Questo si applica davvero quando si dispone di più pezzi di documentazione su cui lavorare, come un libro o una guida in linea per un'applicazione. Spesso vuoi essere in grado di riferirti a concetti tramite collegamenti in attività, e anche a informazioni di riferimento dettagliate, ma non vuoi impantanare il lettore con questi dettagli. Spesso, quando le persone sono interessate a "farlo semplicemente", vogliono che i passi siano stabiliti per loro e basta. Altre persone amano avere uno sfondo su ciò con cui stanno lavorando prima di provare qualcosa di specifico. Eppure altri vogliono conoscere un livello di dettaglio straziante e scaveranno nei documenti di riferimento.
Prima regola della scrittura tecnica:
Non usare la parola utilizza! In altre parole, le parole più piccole sono migliori se hanno lo stesso significato.
Il mio animaletto ora è fuori dai limiti, posso rispondere in modo più completo. La scrittura tecnica riguarda il pubblico e non lo scrittore. Fai tutto il possibile per far funzionare il testo per il pubblico. Questo include:
Leggi altre domande sui tag documentation technical-writing