Stiamo cercando di documentare una matricola open source project, e speravo in alcuni suggerimenti su buoni metodi e/o strumenti che funzionassero bene per voi. Inoltre, come sviluppatore, preferisci documenti online, documenti basati su wiki, file di aiuto o altri?Consigli per la documentazione con un progetto open source?
Visto che l'applicazione è in fase di sviluppo in C#, uno sguardo ai Doxygen per generare la documentazione API. È estremamente potente (fa la documentazione standard per i membri dello stile di javadoc, ma genererà anche i grafici di call, ereditarietà, dipendenza dei file e collaborazione). Nonostante il suo potere è facile da usare. Può generare documenti API in una miriade di formati: HTML, Latex, manpage, ecc.
Per scrivere manuali, esercitazioni e altri tipi di documentazione più flessibili, prendere seriamente in considerazione l'impostazione di un wiki. Ho usato DokuWiki con molto successo. Ha il supporto per l'evidenziazione della sintassi, quindi è utile per i progetti di codice. Dispone inoltre di ACL utente che saranno utili per un progetto open source. Richiede anche solo PHP e nessun database. Ovviamente offre le funzionalità wiki standard come il controllo delle versioni.
Infine, vorrei ricordare trac, che è un wiki, il controllo di versione, bug tracker ibrido. Vale sicuramente la pena dare un'occhiata.
Anche se non ho in realtà sponsorizzato qualsiasi progetti open source molto del lavoro che faccio è collaborativo. Ho scoperto che un wiki con permessi appropriati è un modo eccellente per le persone di collaborare alla stesura di documenti comuni. Nel mio caso sono in genere storie di sviluppo - io e il cliente lavoriamo per generarli. Penserei che ciò funzionerebbe bene anche con la documentazione collaborativa per il tuo progetto.
Mi piace l'idea di un wiki, in particolare per la sua collaborazione. – ccook
Suona come Sandcastle sarebbe una buona misura per voi.
Il modo totalizzante Io sono a favore è l'uso di un Wiki. Tuttavia, mi piace la possibilità di generare automaticamente documenti dal codice sorgente. Ci sono molti strumenti là fuori ma io sono particolarmente appassionato di SandCastle. Fornisce lo stesso stile dei documenti MSDN che la maggior parte degli sviluppatori .NET dovrebbe avere già con l'uso e sembra che il progetto Open Source sia costruito in .NET. Per quanto posso vedere, l'ultimo framework supportato è .NET 2.0.
I documenti online sono sempre una buona idea, soprattutto quando si utilizza Wiki. Sono più ricercabili, c'è una cronologia tenuta in caso di errori, e sono generalmente più brevi poiché non hanno lo "zucchero" di una lunga documentazione o di un manuale. Tuttavia, è necessario prestare particolare attenzione alla denominazione e ai collegamenti degli articoli.
Se alcune parti del codice del progetto fungono da API, tuttavia, la conoscenza pertinente deve essere acquisita nel codice in modo che possa essere visibile a coloro che la esplorano utilizzando il meccanismo ID al passaggio del mouse sopra una chiamata. La delocalizzazione della conoscenza è un grande problema e le persone sono generalmente riluttanti a fare un cambio di contesto. Se qualcosa appare nella documentazione della testata della funzione, ha una probabilità più alta (sebbene non così elevata) di essere letta che se appare altrove.
Quando si scrive la funzione di documentazione di testa, concentrarsi sulle direttive - le cose che potrebbero influenzare direttamente il cliente. Questi possono essere imperativi (ad es. Chiamare prima X) o informativi (ad esempio, essere consapevoli che X ...).
vedere come gli altri fallo (grandi progetti opensource intendo)
Ma per me a parte il Wiki (menzionato da altri poster) alcuni official documentazione è sempre ays necessari per elementi strutturali/di orientamento. Il wiki è più per knowledge base roba IMHO
Personalmente mi piace Sphinx per la documentazione scritta dagli sviluppatori, in parte a causa di quanto sia bella la documentazione generata in esso. Elabora i documenti scritti in ReST in LaTeX (per la stampa/PDF) o HTML.
Non suggerirei solo utilizzando uno strumento di documentazione API come doxygen. È fantastico se viene anche usato, ma non dovrebbe essere l'unica forma di documentazione.
A seconda di quanto sia attiva la tua comunità di utenti, ti consiglio anche di aggiungere un wiki per ricette o altri tutorial, il suo contenuto può quindi essere piegato nella documentazione di ReST usata da Sphinx a intervalli.
possibile duplicato del [la creazione di grandi documentazione API: Strumenti e tecniche] (http://stackoverflow.com/questions/2001899/creating-great-api-documentation-tools-and-techniques) – Mark
Questa domanda è stato chiesto un anno prima del 'duplicato' :) – ccook