Sono responsabile di trovare un buon modo per documentare il progetto software su cui sto lavorando.Quali sono i modi buoni e cattivi per documentare un progetto software?
Quali sono le cose importanti da documentare? La documentazione di codice e design dovrebbe essere principalmente nel codice sotto forma di commenti? Dovremmo inserire file di testo o documenti di Word direttamente nel controllo sorgente insieme al codice? Dovremmo usare una wiki?
I fattori su cui riflettere comprendono quanto sia facile per il team attuale creare la documentazione e quanto sia facile per gli altri sviluppatori trovare, correggere ed estendere la documentazione in un secondo momento. La mia esperienza da molti progetti è che gli sviluppatori tendono a non scrivere documentazione perché il sistema per scriverlo è troppo complesso o sviluppatore ostile, e che dopo alcuni anni, i nuovi sviluppatori difficilmente possono trovare la piccola documentazione che è stata scritta.
Sono interessato a quali approcci avete utilizzato in progetti simili. Che cosa ha funzionato bene, cosa non ha funzionato bene e perché?
Alcuni fatti chiave sul progetto:
- La piattaforma è C# e .NET.
- Utilizziamo Visual Studio e Team Foundation Server per il controllo del codice sorgente e la gestione degli elementi di lavoro (attività).
- Utilizziamo Scrum e lo sviluppo basato su test e siamo ispirati dal design basato sul dominio.
- Il software è costituito da una raccolta di servizi Web e due client GUI.
- Altri clienti si integreranno con i servizi Web in futuro. L'integrazione verrà eseguita da altri sviluppatori su altri team (quindi i servizi Web formano una sorta di API).
- SharePoint è ampiamente utilizzato in tutto l'ambiente di sviluppo. La maggior parte dei progetti ha un sito di SharePoint, incluso il nostro.
- Sul sito di SharePoint del nostro progetto abbiamo attualmente un sacco di documenti MS Office su aspetti quali requisiti, design, presentazioni per gli stakeholder, ecc. Mantenere tutto aggiornato è difficile.
- Abbiamo anche un wiki di SharePoint solo per il team di sviluppo, dove documentiamo le cose in modo non strutturato mentre procediamo. Gli esempi includono come sono organizzati i nostri script di compilazione, la nostra politica di test, le linee guida per la codifica.
- Il software è un'applicazione interna in un istituto finanziario abbastanza grande.
- Il software è sviluppato da un team di sei persone per un periodo di ~ 1 anno.
- Gli sviluppatori sono consulenti assunti solo per questo progetto e non saranno disponibili per aiutare in futuro (a meno che il cliente non decida di pagare per questo).
- Il cliente ha poche linee guida su come questo tipo di progetto dovrebbe essere documentato.
Si prega di esaminare queste domande: http://stackoverflow.com/questions/tagged/documentation. Quali di questi si applicano alla tua situazione? Come è diversa la tua situazione da questi? Duplicato di http://stackoverflow.com/questions/501074/recommendations-for-documentation-with-an-open-source-project –
Molti di questi sono rilevanti, ma penso che sia utile riavviare la discussione di questo argomento una volta fra poco. Inoltre, gran parte della discussione ruota intorno a quali strumenti usare per la generazione di documenti ecc. Sono più interessato ai concetti, perché alcuni approcci funzionano e perché altri falliscono. – jonsb
@jonsb: Si prega di non "riavviare l'argomento" facendo di nuovo la stessa domanda. Si prega di aggiornare le domande esistenti con nuove informazioni. Si prega di fare riferimento alle domande esistenti. Semplicemente ri-chiedere una domanda esistente è maleducato. Abbiamo già risposto. –