Come gestire la documentazione di un progetto open source? [chiuso]

Una cosa che direi è che la documentazione DEVE essere nei file del codice sorgente (usando qualunque markup che vuoi) e poi i documenti generati automaticamente da questi.
Almeno sul tuo sito, puoi generare download formattati dei documenti come parte del pacchetto sorgente in modo che l'utente non abbia bisogno di uno strumento doc specifico

La possibilità che qualcun altro aggiusti / aggiunga una funzione e quindi modifichi / aggiunga un po 'di documentazione di markup immediatamente adiacente nello stesso file potrebbe essere bassa, ma la possibilità che trovino un file completamente diverso in un repository diverso per fare il lo stesso è leggermente inferiore a zero.

Puoi sempre avere un tutorial.h che contenga grandi blocchi di testo se lo desideri, ma trattalo come parte dell'origine

Se il tuo progetto è una libreria, niente batte la documentazione in stile javadoc per documentare la sintassi dell'API dai commenti all'interno del codice stesso.

Per quanto riguarda la documentazione su tutorial, esempi di utilizzo, ecc. Raccomando caldamente di utilizzare un formato wiki. Altri progetti che ho visto hanno pagine separate per rami diversi. Quando avvii una nuova diramazione, copia semplicemente le cose che non sono state modificate in una nuova pagina e aggiornate da lì.

La mia ragione per raccomandare un wiki è aneddotica, ma per esperienza personale. Ho contribuito con aggiornamenti di documentazione a progetti open source in diverse occasioni, ma sono stati tutti su wiki. Se sto cercando di capire qualcosa e la documentazione è fuorviante o inutile, dopo averlo capito aggiornerò il wiki mentre sono nei documenti e mi viene in mente. Se non per un senso di rinuncia, almeno perché so che probabilmente avrò bisogno di cercarlo di nuovo io stesso in un anno o due.

Se non c'è una wiki, la barriera di accesso è troppo alta per preoccuparsi, tra capire come viene generata la documentazione, dove è memorizzata, ottenere gli ultimi dal controllo del codice sorgente, come fare le modifiche, rendere effettivi modifiche e navigazione nelle mailing list per ottenere una patch accettata.

Se vuoi avere uno stretto controllo sulla tua documentazione, usa assolutamente quello che ti è più comodo, perché per lo più sarai l'unico ad aggiornarlo. Se vuoi incoraggiare la partecipazione della comunità, usa un wiki.

File di Markdown In hosting con la fonte funziona molto bene.

Gli strumenti docutils basati su RST, ad esempio, possono creare HTML o LaTex (e PDF) da un set di documenti.

Questo - in effetti - combina l'opzione 1 e l'opzione 3.

Se non ti dispiace convertire i documenti da Markdown a reStructuredText, prendi in considerazione Sfinge . È facile come il markdown, ma è molto più potente.