Dove mettere la documentazione del codice?

Attualmente sto usando due sistemi per scrivere la documentazione del codice (sto usando C ++):

• La documentazione relativa ai metodi e ai membri della classe viene aggiunta accanto al codice, utilizzando il formato Doxygen. Su un server Doxygen viene eseguito sulle fonti in modo che l'output possa essere visualizzato in un browser web
• Le pagine di panoramica (che descrivono un insieme di classi, la struttura dell'applicazione, il codice di esempio, ...) vengono aggiunte a un Wiki

Personalmente penso che questo approccio sia semplice perché la documentazione relativa ai membri e alle classi è molto vicina al codice, mentre le pagine di panoramica sono davvero facili da modificare nel Wiki (ed è anche facile aggiungere immagini, tabelle, ...). Un browser Web consente di visualizzare entrambe le documentazioni.

Il mio collega ora suggerisce di mettere tutto in Doxygen, perché possiamo quindi creare un grande file di aiuto con tutto ciò che contiene (utilizzando HTML WorkShop di Microsoft o Qt Assistant). La mia preoccupazione è che la modifica della documentazione in stile Doxygen sia molto più difficile (rispetto a Wiki), specialmente quando si desidera aggiungere tabelle, immagini, ... (o esiste uno strumento di "anteprima" per Doxygen che non richiede di generare il codice prima di poter vedere il risultato?)

Che cosa usano i grandi progetti open source (o chiusi) per scrivere la documentazione del loro codice? Lo dividono anche tra stile Doxygen e Wiki? O usano un altro sistema?

Qual è il modo più appropriato per esporre la documentazione? Tramite un server Web / browser o tramite un file di aiuto di grandi dimensioni (diversi 100 MB)?

Quale approccio segui quando scrivi la documentazione del codice?

Avere tutta la documentazione in un sistema anziché in due può essere un vero vantaggio. Cose come il backup e il ripristino, il versioning, la ricerca globale, la ricerca globale e la sostituzione, il collegamento incrociato e, come hai scritto, mettendo tutti i documenti in un documento finale, in genere funzionano con meno "attriti" quando non devi mantenere due diversi sistemi con capacità sovrapposte.

D'altra parte, devi pensare se questi vantaggi superano la facilità del tuo Wiki. Il cerchio modifica / genera / perfeziona modifica / genera di nuovo potrebbe essere più veloce con il tuo Wiki. Immagino che tu possa ottenere quel ciclo abbastanza velocemente con doxygen mantenendo le tue pagine di panoramica come un sottoprogetto separato di doxygen. È possibile utilizzare le funzionalità di collegamento esterno di doxygen, che non sostituisce una "anteprima rapida", ovviamente, ma un passo in quella direzione. Non l'ho fatto da solo, finora, ma immagino che tu debba provarlo da solo se vuoi sapere se funziona nel tuo caso.

Per quanto riguarda altri progetti: penso che uno strumento come doxygen sia principalmente per la documentazione di biblioteca. Se non sei un fornitore di librerie di terze parti e tutti coloro che usano le tue librerie hanno pieno accesso al codice sorgente, allora la necessità di uno strumento come doxygen è discutibile. Nel nostro team, ad esempio, non abbiamo quasi documenti esterni al di fuori del codice tranne i documenti per l'utente finale e i documenti dei nostri modelli di database. I nostri strumenti principali per quel tipo di documentazione sono docbook e fop , che ci danno risultati soddisfacenti.

Utilizzare prima la documentazione del codice. Aggiungi Wiki e altri metodi, se possibile

So che sarà difficile mantenerlo.

Risposta pratica:

In termini pratici, la prima cosa che fanno gli sviluppatori, è controllare il codice.

Come sviluppatore, mi piace avere documentazione esterna, come Wiki (s), manuali. Ma la prima cosa che faccio è rivedere il codice (a volte da altri sviluppatori, a volte il mio).

Come sviluppatore, che ha lavorato in diversi progetti e clienti, faccio il possibile per aggiungere documentazione esterna, ma è comune avere un sacco di carico di lavoro e non sono stato in grado di supportare un wiki.

A volte, i project manager e altri capi non si preoccupano della documentazione, a volte altri sviluppatori no.

E, il meglio che posso fare, è aggiungere alcuni commenti al codice.

In bocca al lupo

Alcuni usano altri sistemi - dai un'occhiata alla Sfinge di Python per esempio, hanno un sistema di documenti all-in-one che costruisce tutto (funziona anche per C / C ++)

Penso sempre che la documentazione sia separata dal codice, doxygen è fantastico, ma è per una panoramica dell'API, non per "documentazione". Per questo, un wiki è fantastico, ma preferisco usare ASCIIDOC e archiviare i risultati di questo nel controllo del codice sorgente insieme al codice, principalmente perché posso generare PDF da esso da consegnare ad altre persone (ad esempio tester, clienti, ecc.)

Doxygen ti consente di creare PDF, HTML, pagine wiki, quasi tutto ciò che ti viene in mente.

La mia preferenza personale è avere sia Doxygen che wiki e una sceneggiatura o qualcosa da controllare quando divergono.

Dalla versione 1.8.0 doxygen supporta Markdown , che dovrebbe rendere l'esperienza di scrittura di pagine statiche altrettanto conveniente come in un sistema Wiki.

Destinatari

Penso che quando rispondi a questa domanda devi davvero chiederti chi è destinato a leggere questa documentazione. Uno sviluppatore ha esigenze sostanzialmente diverse rispetto a un utente o persino a un analista aziendale.

• Come sviluppatore: documentazione associata al codice in fase di studio, dettagli come il contratto di interfaccia ed esempi di utilizzo. Forse una documentazione di alto livello e specifiche del protocollo per una buona misura.
• Come utente: documentazione disponibile tramite il menu di aiuto o un sito Web accessibile su come utilizzare il software.
• Come analista aziendale: la documentazione disponibile come documento o come sito Web accessibile è utile. Una modesta quantità di dettagli su protocolli, architettura di alto livello e casi d'uso sono i migliori.

Manutenzione

Per sapere dove posizionare la fonte per questa documentazione dipenderà dal tuo pubblico e da chi sta scrivendo per il tuo pubblico.

• Hai solo una casa di sviluppatori? Inserisci tutto nel codice. Lo incoraggerà ad essere aggiornato. Dovrai lavorare su una cultura che incoraggi gli aggiornamenti della documentazione a essere importanti quanto le modifiche al codice.
• Hai una casa di sviluppatori e scrittori di documentazione? Dividi le responsabilità. Utilizzare gli strumenti orientati agli sviluppatori per gli sviluppatori, utilizzare gli strumenti degli autori della documentazione per gli autori della documentazione.

Laddove possibile, assicurarsi che sia possibile eseguire esempi di codice o casi d'uso. Automatizza la loro esecuzione e segnala errori interni. È probabile che queste pagine siano una documentazione scadente o negativa.

Inoltre, qualunque strumento tu scelga di scrivere la tua documentazione, hai bisogno di un mezzo affidabile per associare una versione specifica della documentazione a una versione specifica del codice. Ciò è ancora vantaggioso anche in una felice terra delle nuvole con un'unica distribuzione sempreverde.

Documentazione di integrazione

L'integrazione potrebbe essere necessaria per produrre della documentazione, ma si noti che solo l'utente si aspetta che un unico posto acceda a tutta la documentazione di cui ha bisogno.

L'analista aziendale è abbastanza soddisfatto delle specifiche API, delle specifiche di progettazione e degli scenari di utilizzo da collocare in documenti separati o sezioni separate di un sito Web.

Lo sviluppatore preferisce tutto ciò che è visibile dalla fonte, ma è abbastanza felice di avere un paio di documenti di progettazione di alto livello e documenti di specifica del protocollo dettagliati esterni al codice, sebbene preferibilmente all'interno dello stesso checkout.

Il tuo caso

Ad essere onesti, la documentazione nella tua wiki non è probabilmente lo stesso tipo di documentazione nella tua base di codice. Potrebbe non avere senso fondere anche questo.

D'altra parte, l'integrazione dei due può essere garantita in pochi semplici modi.

• Gli strumenti di documentazione di origine (come doxygen) possono produrre html e una wiki vive su un web server. Sarebbe un semplice punto di integrazione servire semplicemente una versione integrata insieme al wiki e collegare tra loro i due.
• Alcuni prodotti wiki ti permetteranno di eseguire il wiki direttamente da un file che puoi archiviare in una base di codice. Ciò fornisce un semplice strumento wysiwyg mantenendo la documentazione accoppiata al codice.
• Possono essere adattati anche altri formati come il pdf, ma ciò dipenderà dagli strumenti specifici che si desidera utilizzare. Potrebbe avere senso raschiare il tuo wiki in file markdown e alimentarlo attraverso doxygen (o altri strumenti). Potrebbe avere senso pdf separatamente il wiki e la fonte e utilizzare uno strumento di fusione pdf.

Alla fine, scopri quale sistema di documentazione ha bassi costi di manutenzione e ti assiste nel fornire un prodotto di alta qualità visto dal tuo pubblico di sviluppatori, analisti aziendali e utenti. Tutto ciò che impedisce uno di questi gruppi ridurrà necessariamente la qualità dei prodotti.

Se stai usando ASCII, dovresti archiviare i dati della tua documentazione nascosta nella parte alta del tuo codice sorgente! Quindi solo gli utenti più intelligenti (leggi: meritevoli) hanno l'opportunità di utilizzare i tuoi documenti.

Avere documentazione in un formato portatile ben definito, facilmente esportabile potrebbe essere il vero vantaggio. Se la sfinge muore (è improbabile) mi limiterò a convertirmi in un altro sistema, che immagino sarebbe un compito programmabile. Spostare i dati dal wiki (presumibilmente memorizzati nel database in un formato proprietario potrebbe essere una seccatura).