Che aspetto ha la tua documentazione tecnica? [duplicare]

Ho scritto - e ho beneficiato - il seguente:

• Documenti di architettura che spiegano il sistema o un singolo componente nel suo complesso. Questi sono grandi per i nuovi assunti da leggere per ottenere il "quadro generale" su come funzionano le tue cose. In genere contengono diagrammi di alto livello che spiegano come le diverse parti del sistema comunicano tra loro, insieme a una spiegazione di ciascun componente del sistema, qual è il suo ruolo, ecc.

• Documenti di progettazione formale; durante la scrittura di questi, ognuno è preparato con una caratteristica specifica in mente, e passa attraverso un processo di revisione formale. Sebbene questi non sempre rimangano aggiornati per anni, offrono una visione approfondita di ogni singola caratteristica. Questa documentazione elenca i requisiti formali, i diagrammi del flusso di dati, i diagrammi delle classi e dettaglia le modifiche al sistema per area tecnica (database, middleware, interfaccia utente, ecc.). Potrebbe essere difficile (se non impossibile) scrivere questi after-the-fact, però. La tua scommessa migliore con questi documenti è includerli come parte del processo di sviluppo, se ha senso per la tua squadra.

• Commenti nel codice che possono essere trasformati in documentazione API, come JavaDoc. Questi sono buoni da avere come riferimento, per spiegare le cose ad un livello molto più basso.

Potresti non essere quello che li prepara, ma possono anche essere utili:

• Manuali per gli utenti, guide, ecc. - Per un nuovo noleggio, questi possono essere utili per avere una prospettiva diversa su come il prodotto reale è rientrato per essere utilizzato dai clienti.
• Piani di test - Molto noioso da leggere e più "documentazione interattiva", ma a volte il modo migliore per una nuova assunzione da apprendere è quella di eseguire i test case su un sistema reale.

I documenti dei requisiti possono anche essere utili a seconda di come sono scritti, anche se onestamente ho trovato altre forme di documentazione più utili per capire come funziona il sistema. I documenti dei requisiti sono migliori per guidare gli sforzi di progettazione.

Per i neofiti dovresti anche documentare brevemente la struttura del tuo codice sorgente, i processi di check-in / out, dove trovare gli strumenti, ecc. Poi, quando arriva una nuova persona, chiedi loro di aggiornare il documento e aggiungere ciò che sentono mancava.

Ti consiglio vivamente di consultare doxygen e modificare i file sorgente in modo appropriato. Quindi esegui doxygen e genera una documentazione tecnica sufficiente come la gerarchia delle classi ecc.

In effetti fai di doxygen parte del processo di costruzione e continua a seguire la convenzione di commento mentre procedi.

Solo l'architettura e il design di classe non sono sufficienti per i grandi progetti. Ecco il minimo:

1. Si prega di documentare le variabili globali. Nessuna eccezione.
2. Se una funzione modifica qualcosa oltre ai suoi input, specifica lo stesso.
3. Qualsiasi cosa non banale che sta facendo qualche routine. In particolare, se si implementa un algoritmo complesso, includere un riferimento a quell'algoritmo url o carta.
4. Hack conosciuti che hai inserito e ti aveva promesso di aggiustarlo durante il fine settimana.

Dipende per chi scrivi la documentazione. Se lo scrivi per i programmatori di compagni, dovrebbe probabilmente essere la documentazione nel codice, lasciare che siano commenti o più formale documentazione doxygen. D'altra parte, se il tuo manager o cliente desidera conoscere i dettagli tecnici, un elenco di classi e quello che fanno non dirà loro molto. Quindi in tal caso potresti prendere in considerazione la possibilità di avere diagrammi e descrizioni di alto livello. Per gli utenti finali, probabilmente vorrai alcune domande frequenti, un manuale per l'utente e suggerimenti per gli strumenti (in caso di applicazione della GUI).

In azienda lavoro, non abbiamo clienti e nessun manuale utente. Ma abbiamo sia documentazione di alto livello con logica, obiettivi, architettura astratta ecc., Abbiamo documenti con topologia di rete, metriche di latenza, ecc. E, naturalmente, documentiamo il codice (usando Doxygen) e viaggi e trucchi nelle nostre aziende wiki. A parte questo, abbiamo JIRA dove puoi trovare chi sta lavorando su cosa, cosa è stato fatto e quali azioni sono state eseguite.

Di seguito sono riportati i documenti che consiglierò. Anche se inserisci i commenti nel codice, sento che dovresti sapere qualcosa su cosa sta facendo il codice prima di passare al codice. 1) Utilizzare i documenti del caso / Requisiti dettagliati
2) Documento di progettazione
3) Documenti del caso di test unitario
4) Documenti di test di integrazione