Un buon modo per documentare il tuo software (prodotto)? [chiuso]

Una parola: Doxygen. Si adatta a tutte le tue esigenze. È possibile utilizzare l'output per generare HTM semplice o creare un file CHM o output in lattice e molti altri. Collega automaticamente i nomi delle classi nel testo. Per i nomi dei metodi devi solo aggiungere @see o @ref. È molto semplice da imparare e non dovrebbe richiedere più di 2-3 ore per familiarizzare con i tag di base. Ti avvertirà se i parametri sono mancanti o errati. Puoi facilmente aggiungere un file CSS che genererà il look per la documentazione. E puoi farlo con il codice stesso così non ti devi preoccupare di tenere due diversi set di file.

Una caratteristica che ho veramente apprezzato è la capacità di integrare graphviz per generare automaticamente diagrammi di collaborazione UML. Provalo una volta. Meglio di tutto è totalmente gratuito.

Un sacco di lingue moderne hanno standard associati per generare documentazione per il loro codice (ad esempio javadoc e pydoc ). Questi ti permettono di usare commenti strutturati nel tuo codice per generare documentazione esterna per il codice. Doxygen è un esempio non specifico di una determinata lingua.

Per quanto riguarda le parti del manuale dell'utente che non sono direttamente legate a un'API, potrebbe essere necessario guardare un po 'oltre. Direi che quegli strumenti potrebbero fornire funzionalità oltre a documentare la struttura del codice. Tuttavia, per un progetto a cui sto lavorando, abbiamo finito con l'utilizzo di JavaHelp per fornire collegamenti sensibili al contesto al nostro manuale utente. JavaHelp finisce per essere solo una directory di file html di base per ogni pagina e alcuni file xml per definire la gerarchia e i collegamenti sensibili al contesto.

Un Wiki è il modo migliore per documentare tutte le cose che menzioni. Usiamo MoinMoin, con il suo ricco sistema plug-in è possibile gestire facilmente un corpus di conoscenze dal vivo e consegnare in qualsiasi formato desiderato. Se riesci a ottenere il tuo contenuto in DocBook puoi convertirlo in qualsiasi altro formato di consegna binaria che desideri.

Sono un architetto java e utilizzo Omondo EclipseUML per fornire documentazioni.

Come funziona:

È piuttosto facile perché in primo luogo ho invertito il progetto completo utilizzando la funzione di reverse engineering.

Quindi inverto anche gli altri file jar usati dall'applicazione. Significa che mostro dove sono le chiamate agli altri framework. Significa che posso mescolare il file jar Framework con il codice .class con il mio progetto che ha il codice .java. Vedi di più su: link

Ora ho un modello di grandi dimensioni composto dal mio codice e da più framework che sono stati uniti. Ognuno è una piccola parte del modello del mio singolo modello. Tutte le informazioni sul mio modello sono quindi unite insieme, ma sono comunque molto leggibili.

Finalmente creo le viste dei diagrammi delle classi dal mio modello trascinandole e aggiungendo i miei commenti. Ogni diagramma spiega un concetto e una parte specifica dell'architettura. Generalmente creo circa 100 diagrammi per un grande progetto. Penso che gli sviluppatori non abbiano bisogno di più di 3 ore per iniziare a codificare all'interno di un codice esistente e aggiungere il codice necessario nel posto giusto senza rompere l'architettura esistente.

Gli sviluppatori mantengono i miei diagrammi come documentazione visiva e penso che lo confrontino con il documento java. Tutti i miei diagrammi creati una volta sono solo modelli e non più correlati al codice. Significa che una volta che il codice è stato documentato dai diagrammi UML, possiamo decidere di mantenerlo in sincronia o meno. Preferisco separarli e ad ogni iterazione per unire il mio codice ancora una volta.