Cosa rende buona la documentazione? [duplicare]

Mi piacciono gli esempi. Se hai un'API che esegue una varietà di operazioni foo su oggetti bar , includi esempi pratici , non solo una singola riga che mostra come chiamare la funzione.

Assicurati inoltre di includere da qualche parte una panoramica di "grande immagine" di alto livello su qualsiasi cosa venga documentata. È bello conoscere i diversi tipi di operazioni di foo disponibili, ma è anche utile sapere perché ci sono diverse varianti e alcune guide per sapere quando usare quale variante.

Per alcuni sistemi, anche un breve manuale per gli utenti incentrato sugli sviluppatori è buono. Questo è importante se i nuovi sviluppatori non sanno nemmeno di usare le parti esistenti del progetto.

Una guida di installazione per la compilazione e la compilazione è anche molto importante se l'installazione non è banale (più che aggiungere file al progetto IDE e fare clic su "compila"). Ciò potrebbe includere connessioni al database e configurazione del server.

Voglio sapere perché .

La documentazione, che sia un commento o un file Word, non dovrebbe rendere ridondante il codice. So cosa fa il codice - è proprio lì per me da leggere. Voglio sapere perché ...

• Esiste. Che scopo soddisfa?
• È stato scritto in questo modo. È stato solo il primo modo che ti è venuto in mente, o c'è una buona ragione per quel brutto blocco try ?
• È stato progettato in questo modo. Se hai creato una classe che consente la comunicazione con il codice legacy, ma non ha senso se non esistesse legacy, voglio sapere che prima di andare, "A cosa stava pensando questo idiota?"

Dal momento che ho visto solo una piccola menzione: Screenshots!

Anche per gli strumenti solo CLI, può aiutare a consolidare determinati concetti. Un metodo che utilizzo è catturare l'intera finestra con un po 'di background. Quindi cambierò lo sfondo per gli scatti successivi. Aiuta a distinguere le immagini, soprattutto per le persone che tornano a fare riferimento. Vedi, per esempio ...

Inoltre, screencast! È fantastico avere materiale di riferimento nel testo, ma quando si entra in uno strumento per la prima volta è ancora meglio avere qualcuno a cui familiarizzare passo dopo passo le basi dell'interfaccia.

Guide passo-passo.

Preferibilmente su wiki, in modo che possano essere modificati non appena qualcosa deve essere aggiornato.

The purpose of the documentation is to make it easy [for developers] to update or finish projects

Quindi la buona documentazione raggiunge questo scopo.

Per rendere la buona documentazione, ottieni alcune informazioni dalle persone che useranno la tua documentazione.

Domanda 1. Cosa non possono fare ora? Perché non sono in grado di aggiornare o completare un progetto?

Raccogli le risposte alla domanda da tutte le persone coinvolte. Stakeholder e non stakeholder.

Una volta che hai dei motivi, devi trovare le cause per questi motivi.

Domanda 2. Cosa impedisce loro di aggiornare o terminare un progetto?

Raccogli le risposte alla domanda da parte di tutti gli interessati.

Una volta che hai avuto le cause principali, devi trovare alcune soluzioni a questi problemi.

Domanda 3. Quali cambiamenti potrebbero aiutare ad aggiornare o completare un progetto?

Idealmente, la risposta a questa domanda è "più informazioni, in particolare ..."

Se è così, questo è ciò che la documentazione includerà, le informazioni specifiche richieste. La domanda 3 ti dice specificamente cosa rende la buona documentazione.

Se, d'altra parte, l'informazione non è la soluzione, smetti di scrivere la documentazione. Continua a scavare in causa ed effetto e risolvi il problema.

• Indica l'obiettivo (scopo) della documentazione all'inizio.
• Includi un sommario se la documentazione si estende su più pagine.
• Sii il più specifico possibile quando scrivi qualcosa.
• Tutto nella tua testa dovrebbe essere su carta.
• Includi figure e schermate laddove appropriato quando visualizzano ciò di cui stai scrivendo.

Saprai se la documentazione è buona se dopo diversi mesi hai bisogno di leggerla di nuovo e puoi capire tutto ciò che hai scritto e che ha senso.

Gli esempi dovrebbero essere must. E dal mio punto di vista (come studente), la persona che sta visualizzando il tuo documento non dovrebbe cercare molto.

Il tuo documento dovrebbe avere una buona gerarchia , in modo che ottenere un'informazione sia davvero semplice:)

Prova la documentazione esattamente come un test di usabilità. Consegnare il documento a un utente senza spiegazioni e guardarsi alle spalle per vedere se ne ricavano qualsiasi valore. Spero che soddisfi il tuo obiettivo.

Utilizza un approccio iterativo alla documentazione scritta. Dopo aver scritto una serie di istruzioni di base, procedi nel seguente modo:

1. Consegna il documento a un utente. Chiedi loro di usarlo per eseguire l'operazione.
2. Annota eventuali domande o problemi che incontrano.
3. Modifica il documento per rispondere alle domande o ai problemi.
4. Ripeti.

Hai finito quando il tuo utente non ha più domande o problemi.

Scrivi test.

Quello che più desidero quando prendo in carico un progetto è un buon set di test automatizzati. Per buono, intendo:

• Eseguono tutti,
• Sono chiaramente scritti,
• Trasmettono sia loro il perché che il cosa, e
• Sono più o meno completi.

Mi piacciono i test meglio dei normali documenti perché un computer può verificare che si applichino ancora. Fondamentalmente, i test sono documentazione eseguibile.

Inoltre, mi piacerebbe un documento di 1-3 pagine sull'architettura di sistema, oltre a una base di codice ben organizzata e ben denominata.

Per i programmi Java ci sono due cose che fanno davvero la differenza:

• Test delle unità funzionali che mostrano come utilizzare il codice. Per il codice sviluppato con progettazione basata su test, in sostanza è la specifica in forma eseguibile.
• javadoc - ovvero i frammenti HTML incorporati che finiscono nel link tranne per tuo codice.

Ben fatto, questi due insieme possono rappresentare - IMHO - circa il 90% della documentazione.

Per gettare qualcosa del secolo scorso che è diventato quasi un'arte morta:

Un buon indice . Con ciò intendo riferimenti chiave incoraggiati, ulteriori riferimenti (rilevanti) e ulteriori informazioni / esempi sotto elencati. Esempi selezionati. Riferimenti multipli a diversi usi e sinonimi. Numeri di pagina accurati (o collegamenti). La maggior parte dei libri di tecnologia falliscono completamente in questi giorni. (Sono stupito che nessuno abbia ancora menzionato gli indici)

Pensando da una prospettiva doc dell'API, un buon riferimento incrociato a chiamate alternative e il motivo per cui potresti volere. "Cercando di stampare un grafico? Probabilmente hai bisogno di gfxPrint non stampare, vedi pp 888" ecc.

Rende l'apprendimento andare molto più veloce quando hai superato gli esempi lavorati e vuoi volare da solo - 10 minuti di google ogni chiamata di api non è utile.

JFGI o una casella di ricerca non è sufficiente in quanto otterrà l'80% di riferimenti non pertinenti all'API e spesso non raccoglie facilmente il riferimento giusto o il caso in cui stai cercando su Google quello sbagliato.