All'inizio pensavo che anche le persone che scrivevano il codice avrebbero dovuto documentarlo. Ma ci sono ragioni per le quali questo potrebbe non essere vero. Una persona che è nuova al codice potrebbe porre le domande giuste che potrebbero essere liquidate come "ovvie" dall'autore.
La mia domanda è se esiste una pratica (o pratica) consolidata, e qual è il ragionamento dietro di essi / loro?
Sembra che tu stia supponendo che la documentazione sia scritta una volta e mai aggiornata. Questo può essere vero se il tuo software non cambia mai dopo che è stato scritto, ma probabilmente non è così. Proprio come è possibile rifattorizzare il codice per migliorare la leggibilità e la manutenibilità, la documentazione dovrebbe anche essere in un formato che promuova la capacità di refactoring. Gli autori del codice iniziale sono buoni candidati per scrivere la documentazione iniziale, ma le persone che gestiscono il codice dovranno anche conservare la documentazione. Se gli autori esistenti sono ancora in giro e stanno rispondendo alle domande dei nuovi manutentori, a qualcuno (o agli autori originali o ai nuovi manutentori) dovrebbe essere assegnato il compito di assicurarsi che la documentazione sia più completa.
L'esatta suddivisione dei ruoli e delle responsabilità dipende dall'organizzazione. In alcuni punti, gli sviluppatori sono responsabili di qualsiasi cosa nel file di codice (documentazione API e commenti in linea) e gli sviluppatori e i tester supportano scrittori tecnici che scrivono e conservano documenti. In altre organizzazioni, il team di sviluppo può scrivere tutto.
Alla fine della giornata, non importa chi scrive e mantiene la documentazione, a patto che venga mantenuta. Dopotutto, la documentazione sbagliata è probabilmente peggiore del non avere affatto documentazione.
Nella mia esperienza il problema più grande della documentazione è che spesso non dipinge l'immagine che conta, che espone un modello di alto livello e poi ingrandisce. Se lasci che gli sviluppatori scrivano la documentazione ottieni una ripetizione del codice in linguaggio naturale che è assolutamente inutile sia per gli altri sviluppatori che per gli utenti. La documentazione dovrebbe essere scritta nel corso di analisi e progettazione da parte di analisti e progettisti, non come un ripensamento di coloro che hanno digitato il codice. Se sei fortunato è la stessa persona che non è troppo autentica e ha un po 'di immaginazione. Sfortunatamente la documentazione è spesso qualcosa che qualcuno deve fare prima che il progetto possa essere contrassegnato come fatto.
E sì, dovrebbe essere rivisitato che potrebbe essere fatto dagli sviluppatori ma il framework dovrebbe già essere lì, creato da persone che conoscono il perché, il dove e il come piuttosto che il solo. Riguarda il contesto, fornendo riferimenti ai nuovi arrivati su cui possono costruire la loro comprensione.
Leggi altre domande sui tag documentation