Dove mettere la documentazione del codice?

Avere tutta la documentazione nel sistema one invece di due può essere un vantaggio reale. Cose come backup & ripristino, versioning, ricerca globale, ricerca globale e sostituzione, cross-linking e, come hai scritto, mettendo tutti i documenti in un documento finale, in genere funzionano con meno "attrito" quando non devi mantenere due sistemi diversi con capabiliti sovrapposti.

D'altra parte, devi pensare se questi vantaggi superano la facilità del tuo Wiki. Il cerchio modifica / genera / perfeziona modifica / genera di nuovo può essere più veloce con il tuo Wiki. Immagino che tu possa ottenere quel ciclo abbastanza velocemente con doxygen mantenendo le pagine panoramiche come un sottoprogetto Doxygen separato. Puoi utilizzare le funzionalità collegamento esterno di doxygen, che non è una sostituzione per una "anteprima veloce", ovviamente, ma un passo in quella direzione. Non l'ho fatto da solo, finora, ma credo che devi provarlo per te stesso se vuoi sapere se funziona nel tuo caso.

Riguardo ad altri progetti: penso che uno strumento come doxygen sia principalmente per la documentazione della biblioteca. Se non si è un fornitore di librerie di terze parti e chiunque utilizza le proprie librerie ha pieno accesso al codice sorgente, 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 degli utenti finali e i documenti dei nostri modelli di database. I nostri strumenti principali per questo tipo di documentazione sono docbook e fop , che ci dà risultati soddisfacenti.

Utilizza prima la Documentazione del codice. Aggiungi Wiki e amp; altri metodi, se possibile

Lo so, sarà difficile, per mantenerlo.

Risposta pratica:

In termini pratici, la prima cosa che gli sviluppatori fanno è 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 amp; clienti, faccio il possibile per aggiungere documentazione esterna, ma è normale avere molto carico di lavoro e non essere in grado di supportare un wiki.

A volte, i project manager, & altri capi, non si preoccupa della documentazione, a volte gli altri sviluppatori non lo fanno.

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

Good Luck

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

La mia preferenza personale è avere Doxygen e wiki e uno script o qualcosa da controllare quando divergono.

Alcuni usano altri sistemi - dai un'occhiata a Sphinx di Python per esempio, hanno un sistema doc 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 la "documentazione". Per questo, un wiki è fantastico, ma preferisco usare ASCIIDOC e memorizzare i risultati di questo nel controllo sorgente insieme a il codice, principalmente perché posso generare PDF da esso a mano ad altre persone (ad esempio, tester, clienti, ecc.)

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

Pubblico di destinazione

Penso che quando rispondi a questa domanda devi davvero chiederti chi è destinato a leggere questa documentazione. Uno sviluppatore ha esigenze molto diverse per un utente o anche un analista di business.

• Come sviluppatore: documentazione associata al codice studiato, dettagli come il contratto di interfaccia ed esempi di utilizzo. Forse una documentazione di alto livello e le 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.
• In qualità di 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

Quanto a dove posizionare il sorgente di questa documentazione dipenderà dal tuo pubblico e da chi scrive per il tuo pubblico.

• Hai solo una casa di sviluppatori? Metti tutto nel codice. Lo incoraggerà ad essere aggiornato. Avrai bisogno di lavorare su una cultura che incoraggi gli aggiornamenti della documentazione sia importante quanto le modifiche al codice.
• Avere una casa di sviluppatori e scrittori di documentazione? Dividi le responsabilità. Utilizza gli strumenti orientati agli sviluppatori per gli sviluppatori, usa gli strumenti di documentazione per gli scrittori di documentazione.

Dove possibile, assicurati che possano essere eseguiti esempi di codice o casi d'uso. Automatizza la loro esecuzione e contrassegna internamente i guasti. È probabile che queste pagine siano di scarsa o cattiva documentazione.

Inoltre, a prescindere dagli strumenti in cui si sceglie di scrivere la documentazione, è necessario un mezzo affidabile per associare una versione specifica della documentazione a una versione specifica del codice. Ciò è ancora vantaggioso anche in una felice nuvola di terra con una singola distribuzione sempreverde.

Integrazione della documentazione

Potrebbe essere necessaria l'integrazione per produrre alcuni documenti, ma si noti che solo l'utente si aspetta che un singolo luogo acceda a tutta la documentazione di cui ha bisogno.

L'analista di business è piuttosto soddisfatto delle specifiche API, Designs Specs e Use da collocare in documenti separati o sezioni separate di un sito Web.

Lo sviluppatore preferisce tutto visibile dalla sorgente, ma è abbastanza contento di avere un paio di documenti di progettazione di alto livello e documenti dettagliati di specifica del protocollo esterni al codice, anche se preferibilmente all'interno della stessa cassa.

Il tuo caso

Per essere onesti, la documentazione nel tuo wiki probabilmente non è lo stesso tipo di documentazione nel tuo codice base. Potrebbe non avere senso unire anche quello.

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

• Gli strumenti di documentazione di origine (come doxygen) possono produrre html e un wiki vive su un server web. Sarebbe un semplice punto di integrazione servire semplicemente una versione costruita a fianco del wiki e collegare tra loro i due.
• Alcuni prodotti wiki ti permetteranno di eseguire la wiki direttamente da un file che puoi effettuare il check-in su un code-base. Questo fornisce un semplice tool wysiwyg mantenendo la documentazione accoppiata al codice.
• Anche altri formati come il pdf possono essere adattati, ma ciò dipende dagli strumenti specifici che desideri utilizzare. Potrebbe avere senso analizzare la tua wiki in file markdown e alimentarla tramite doxygen (o altri strumenti). Potrebbe avere senso inserire in pdf il wiki e l'origine separatamente e utilizzare uno strumento di fusione pdf.

Alla fine della giornata, scopri quale sistema di documentazione ha bassi costi di manutenzione e ti aiuta a fornire un prodotto di alta qualità visto dal tuo pubblico di sviluppatori, analisti aziendali e utenti. Qualsiasi cosa che impedisca uno di questi gruppi ridurrà necessariamente la qualità dei prodotti.

Se usi ASCII, dovresti nascondere i tuoi dati di documentazione nel bit più alto del tuo codice sorgente! Quindi solo i più intelligenti (leggi: meritevoli) degli utenti hanno l'opportunità di utilizzare i tuoi documenti.

Avere la documentazione in un formato portatile ben definito, facilmente esportabile, potrebbe essere il vero vantaggio. Se sfinge muore (improbabile) mi limiterò a convertire in altro sistema, che suppongo sarebbe un compito programmabile. Spostare dati da wiki (presumibilmente memorizzati nel database in un formato proprietario potrebbe essere un problema).