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

Sono il creatore di un progetto open source in crescita. Attualmente, sto diventando frustrato cercando di capire il modo migliore per gestire la documentazione. Ecco le opzioni che ho considerato:

• Sito Web HTML
• A Github Wiki
• File Markdown ospitati su Github
• Inserimento di tutti i documenti in Github README.md

La documentazione è già scritta in Markdown, non riesco proprio a capire come voglio renderla disponibile. Sono davvero attratto da Git poiché posso diramare e taggare la documentazione proprio come posso ramificare e taggare la fonte.

Potrei usare una libreria Markdown per tradurre Markdown in HTML e visualizzarlo su un sito Web in stile. Avrei bisogno di caricare le modifiche sul sito Web ogni volta che si verificava una modifica e sarebbe difficile gestire tutti i diversi "tag" della documentazione.

I wiki di Github (per quanto ne so) non cambiano in base al ramo in cui ti trovi. Quindi, potrei avere solo la versione "master" della documentazione nel modulo Wiki di Github in qualsiasi momento.

Mettere tutto nel README di Github è un po 'pulito. Ricevo ramificazioni e tag, ma è un po 'stancante da usare e non si presta bene alla navigazione facile.

Mi sto perdendo qualche soluzione fantastica? Quali altre opzioni ho?

Una cosa che direi è che la documentazione DEVE essere nei file del codice sorgente (usando qualsiasi markup desiderato) e quindi 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 per documenti specifico

Le possibilità che qualcun altro corregga / aggiunga una funzione e quindi modifichi / aggiunga un po 'di documentazione di markup immediatamente adiacente nello stesso file può essere bassa MA la possibilità che trovino un file completamente diverso in un repository di documenti diverso per fare lo stesso è leggermente meno di zero.

Puoi sempre avere un tutorial.h che contiene grandi blocchi di testo, se lo desideri, ma trattalo come parte della fonte

Se il tuo progetto è una libreria, niente è meglio della 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. Consiglio vivamente di usare un formato wiki. Altri progetti che ho visto hanno pagine separate per diversi rami. Quando si avvia una nuova filiale, è sufficiente copiare le cose che non sono cambiate in una nuova pagina e aggiornare da lì.

La mia ragione per raccomandare una wiki è aneddotica, ma per esperienza personale. Ho apportato 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 ed è fresco nella mia mente. Se non per un senso di restituzione, almeno perché so che probabilmente dovrò cercarlo di nuovo da solo tra un anno o due.

Se non esiste un wiki, la barriera all'ingresso è troppo alta per disturbare, tra capire come viene generata la documentazione, dove viene archiviata, ottenere le ultime dal controllo del codice sorgente, come apportare modifiche, apportare le modifiche effettive e navigare nelle mailing list per ottenere una patch accettata.

Se desideri uno stretto controllo sulla tua documentazione, usa sicuramente tutto ciò che è più comodo per te, perché sarai principalmente l'unico ad aggiornarla. Se vuoi incoraggiare la partecipazione della comunità, usa un wiki.

I file di markdown ospitati con il sorgente funzionano molto bene.

Gli strumenti di 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, considera Sphinx . È facile come il markdown, ma è molto più potente.