Guida API / Scrittori tecnici [chiusa]

Il mio consiglio è di guardare tutorial che consideri validi e copiare il loro stile.

Alcune cose che generalmente migliorano la documentazione:

1. essere ridondante. Ripetersi con diversi esempi va contro il rigore degli sviluppatori che amano non ripetersi mai. Ma nella documentazione questo è davvero molto importante. Offre al lettore più di una possibilità di ottenere qualcosa.
2. Esempi. Esempi. Esempi.
3. Cerca di indossare il cappello di un lettore newbie ogni tanto e vedere come si legge. Troverai spesso che stai assumendo molte cose che il lettore non sa.
4. Una buona documentazione di solito è in un formato modificabile / wiki, in modo che possa essere gradualmente migliorata dai lettori.
5. L'umorismo è una buona cosa (ad esempio documenti Python , specialmente le versioni precedenti).
6. Scrivi per le persone, non per le macchine. I programmatori tendono ad essere concisi nella loro documentazione: * (ad esempio "restituisce null in caso di fallimento"). Ma essere solo un po 'più prolisso rende le cose più facili da analizzare e più leggibili (ad es. "La funzione restituisce NULL se non riesce ad aprire il file di input").

Ho fatto documentazione di programmazione per circa 25 anni, dal manuale del programmatore Unix alle app server Microsoft. La documentazione tecnica ha una piramide di priorità:

• È tecnicamente preciso? Questo è il lavoro # 1. Una volta che hai introdotto qualcosa che non è corretto, perdi il lettore.
• È completo? Hai documentato tutti gli argomenti, i valori di ritorno? Hai documentato tutte le eccezioni? Qualche trucco importante? Questi di solito entrano in una sezione commenti / commenti. Ad esempio, se un metodo imposta anche una proprietà pubblica su un valore, dillo al lettore.
• È appropriato? Questa informazione è necessaria allo sviluppatore o stai semplicemente riempiendo lo spazio? A volte è meglio fare riferimento a un URL in cui possono apprendere informazioni tecniche informazioni piuttosto che per tentare di parafrasare o riformularlo in modo errato.

Se possibile, fornisci esempi. In molti casi, uno sviluppatore prenderà un esempio decente e correrà con esso.

I documenti tecnici sono scritti nell'ordine inverso in cui appaiono tipicamente. Di solito scrivi prima la sezione di riferimento, poi una sezione guida / ricettario, poi un'introduzione e infine un tutorial se hai tempo.

E non dimenticare un buon editor. Proprio come uno sviluppatore non dovrebbe testare e verificare il proprio codice, non dovresti modificare i tuoi documenti.

Quasi tutte le aziende di dimensioni decenti hanno una guida allo stile del documento. Ho persino un vecchio testo della Guida allo stile AP dai tempi dell'università. Leggi Strunk e White.

Potresti anche esaminare alcuni corsi universitari comunitari. Come i non sviluppatori che non codificano, i non-scrittori non hanno idea di quanto sia difficile scrivere una discreta documentazione per gli sviluppatori. Se hai mai guardato il codice che hai scritto 3 mesi fa e non riesci a capire cosa diavolo stavi pensando, immagina di provare a documentare il codice di qualcuno che non è più con la compagnia. È più difficile che scrivere il codice in primo luogo.

Stai attento all'umorismo. A seconda delle tue abilità, può essere frainteso. Non lo consiglio Per quanto buona documentazione è stata trovata in un forum dove chiunque può cambiarla, buona fortuna a tenere lontani gli spammer.