Quali sono i modi buoni e cattivi per documentare un progetto software?

Question

Sono responsabile di trovare un buon modo per documentare il progetto software su cui sto lavorando.

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.

Answer 1

Primo e più importante, i commenti devono essere scritti in modo tale che NDoc possa analizzarli. Questo è il modo migliore per documentare il codice stesso, poiché gli sviluppatori devono modificare le loro pratiche di sviluppo molto poco e generare pagine che spieghino il codice senza dover guardare il codice.

In secondo luogo, convincere gli sviluppatori a scrivere la documentazione non è facile, e convincerli a farlo potrebbe essere un esercizio di futilità. È qui che entrano in gioco prodotti come Fogbugz. Aiuteranno a gestire lo sviluppo con i ticket, ti aiuteranno a tenere traccia dei check-in e, quando hai eseguito un'iterazione, a generare note di rilascio.

In conclusione, la soluzione migliore è trovare la soluzione più efficace che si adatti al processo esistente. Se influisce molto poco sul loro processo di sviluppo, sarà più probabile che adottino il sistema.

Answer 2

G'day,

utilizzare Sicuramente un wiki. Consiglierei TWiki perché è un'eccellente ed estesa implementazione di un wiki senza essere troppo complicato da installare e gestire.

Ecco un paio di pensieri iniziali.

Categorie:

iniziare con un'ontologia iniziale di ciò che si desidera catturare, ma

• permettono alle persone di aggiungere nuove categorie o sottocategorie, come richiesto,
• permettere alle persone di retitle (sotto) categorie come richiesto e forse come concordato per questo in modo da non ottenere la frammentazione per più nomi praticamente per la stessa cosa.
• lascia che tutte le (sotto) categorie iniziali avvizziscano e muoiono se rimangono vuote. Fatelo alla fine del progetto poiché alcune aree potrebbero avere solo voci verso la fine di un progetto.

Tagging:

iniziare a utilizzare un tag cloud. Ecco un ottimo plug-in disponibile per TWiki per iniziare a classificare i contenuti nella fase iniziale del progetto. L'aggiornamento dei tag è quasi impossibile. Iniziare a taggare presto consente inoltre alle persone di cercare informazioni che potrebbero già esserci, anziché avere le stesse informazioni in più posizioni.

HTH Tornerò e aggiungerò altri punti mentre li penso.

Answer 3

Peggiore per me della mancanza di documentazione è eccesso di di documentazione.

Tenete a mente che sì: è davvero importante per documentare il progetto, ma anche che la maggior parte della documentazione è sempre a rischio di mai stato letto a tutti.

Quindi, penso che un buon punto di partenza consista nel pensare alla tua documentazione più come qualcosa che potresti usare per introdurre nuovi sviluppatori nel tuo progetto piuttosto che una descrizione troppo dettagliata del funzionamento interno del tuo software.

Answer 4

Penso che le cose più importanti da documentare siano le decisioni . Questo vale per tutto, dai requisiti alle scelte architettoniche. Quali sono i requisiti del modulo X? In che modo questi requisiti sono rappresentati nell'architettura? Perché hai scelto il modello architettonico A su B? Quali sono i vantaggi? Lo stesso vale per il codice sorgente: è risaputo che commentando lo perché lo è decisamente migliore dello come.

Come si documentano queste decisioni non è molto importante a mio parere, sia che si utilizzi un Wiki o un documento dei Requisiti fatto in Word. Ancora più importante è che questi documenti sono sempre aggiornati e che è facile per chiunque accedervi.Questo può essere ottenuto usando un wiki o posizionando i documenti sotto il controllo del codice sorgente, come dici tu. Se solo pochi hanno accesso ad essi, è più probabile che non vengano aggiornati, da non leggere quando necessario.

Utilizziamo un Wiki per il nostro progetto attuale e funziona molto bene. È facile accedere a chiunque (sviluppatori, gestori e clienti) e una cronologia può tenere traccia delle modifiche, in modo da sapere cosa è stato cambiato e perché. Inoltre, cerchiamo di documentare il codice in modo significativo e documentare le principali decisioni di progettazione. Cerchiamo di non documentare troppo, ad es. cose minori, dato che è sempre difficile mantenere quelle cose aggiornate e non ne vale la pena, imho.