Qual è la migliore documentazione che produci e perché?

Il nostro Wiki.

Perché le persone effettivamente lo usano e lo aggiornano.

Penso che la natura di un Wiki si presta al modo in cui gli sviluppatori vogliono lavorare, il che significa solo abbassare i fatti e andare avanti.

È facile e veloce, la ricerca semplifica la ricerca di ciò che stai cercando, riducendo al minimo le possibilità di duplicazione (e il successivo "così è giusto") e hai bisogno di competenze tecniche minime per leggere o cambiare materiale (come contrario a, diciamo, test).

Il controllo delle versioni è automatico, la formattazione è semplice ma efficace, il che significa che il contenuto tende ad essere prioritario rispetto alla bellezza, e non c'è alcuna pressione per avere copertine, tabelle di modifica, riassunti e così via che aggiungono lavoro a poco beneficio. Perché non ha una struttura specifica, le persone si preoccupano solo di mettere giù ciò che è importante, non ciò che si adatta.

Questa è la mia ipotesi sul perché venga utilizzata, ma come gestore dello sviluppo la cosa principale che mi piace è che si abitua e rimane ampiamente aggiornato.

Test ben scritti. Descrivono cosa dovrebbe fare il codice e dimostrano che funziona.

Poiché vengono eseguiti automaticamente con ogni build, non sono mai obsoleti.

Uno dei pazzi dei miei animali domestici è la natura assente o secondaria della documentazione che accompagna praticamente tutti i software open source. Mentre penso che sia fantastico che altri ingegneri rilascino il loro codice in modo da evitare di reinventare la ruota, è frustrante per i denti trovare il codice accompagnato da nient'altro che un file README con pochi esempi di utilizzo. Sì, posso leggere il codice sorgente, ma esempi di codice e alcune considerazioni sui punti di forza e sulle responsabilità del codice farebbero la differenza nel mondo.

Quindi, quando mi sono arrischiato a realizzare i miei progetti open-source, non ho rilasciato il codice fino a quando non avessi scritto una documentazione approfondita che includesse estesi esempi di codice, una guida all'implementazione passo passo e un vero riferimento API. L'ho fatto in TiddlyWiki , un Wiki autonomo in un singolo file HTML, e ho persino usato i tag e creato un indice.

È stato un sacco di lavoro, e non era il tipo di lavoro che mi piace molto (codifica), ma sembrava irresponsabile non includere documentazione veramente utile, e alla fine l'ho fatto perché ero orgoglioso di il progetto. Volevo che fosse del miglior uso possibile per i miei coetanei.

Il conteggio di Javadoc ? Penso che la mia documentazione API sia ragionevolmente ben fatta e mantenuta. Perché? Perché è integrato con il processo di codifica come può essere, e la sua struttura e notazione è sufficientemente standardizzata. Non c'è bisogno di sprecare le cellule cerebrali per pensare a come effettivamente realizzare la documentazione, o collegarla al codice, o alla versione, perché tutto ciò accade solo da solo.

(and source code doesn't count)

Al contrario, il codice di produzione è l'unica documentazione veramente accurata che possiedi. Descrive esattamente cosa fa il tuo programma. Tutto il resto: documenti di design, diagrammi, commenti al codice ... può essere fuorviante.

Questo non vuol dire che non c'è valore in tutte queste cose. C'è molto valore in molti di loro. Ma hanno tutti lo stesso problema. Sono estrapolazioni di ciò che effettivamente fa il codice. In quanto tali, saranno sempre inclini all'inesattezza.

Anche i test unitari non sono immuni da questo. Un test unitario non eseguito può rapidamente non essere sincronizzato con il codice di produzione che si suppone debba testare. E interi libri sono stati scritti su come scrivere buoni test. Il che implica che è altrettanto facile scrivere quelli cattivi.

Questo è il motivo per cui ci si concentra su un codice chiaro e leggibile nelle metodologie Agile. Knuth si riferisce ad esso come programmazione alfabetica. Scrivere il codice in modo che altri possano leggerlo e non solo il compilatore. Tutto il resto punta solo al codice.

La documentazione che scrivo quando so che qualcun altro dovrà prendere il mio codice. Dopo una bozza iniziale, mi siedo con loro e il documento e ripasso il codice. Il documento viene aggiornato in base a questa recensione.

Se la nuova persona fa lo stesso per il terzo sviluppatore, è probabilmente abbastanza approfondito. Poi di nuovo, la maggior parte delle terze versioni sono.

In uno dei miei precedenti lavori prima di partire, uno dei miei compiti era di aiutare con questo documento che conteneva varie informazioni sul codice base, che era un mix di VBScript, JScript e C / C ++ per le parti COM in Oltre ai vari linguaggi di markup come questo era per un dot-com dopo tutto. Credo che fossero quasi una dozzina di pagine quando me ne andai e contenni la maggior parte di ciò che avevo imparato nei circa 9 mesi circa in cui lavoravo lì. Questo è il migliore che ho prodotto a causa di quanto sia il più vicino che ho trovato in una buona discarica di cervello di tutte le cose che avevo in testa nel lavorare con la maggior parte di questo codice. La partenza è stata più di un problema noto quando ho iniziato così, in un certo senso, non era una cosa scioccante ed è stato divertente provare a versare il contenuto del mio cervello in un documento Word.

Uso nei commenti di codice. Li scrivo mentre eseguo il codice e commento ogni blocco che spiega il processo, non le specifiche del modo in cui il codice viene eseguito (nessun commento //set x = y !). Uso javadoc anche durante la scrittura del codice Java, in modo che chiunque utilizzi il codice nel nostro IDE abbia una guida approssimativa immediata su come utilizzare il mio codice.

Per la documentazione di alto livello (struttura di classe, framework e istruzioni di installazione) utilizzo la nostra wiki aziendale. Questo ha messo tutte le informazioni in un unico posto, piuttosto che cercare di distribuire documenti Word ovunque.

Documenti con buoni requisiti

Gli sviluppatori provengono da tutti gli ambiti, ma una specifica dei requisiti ben scritta può colmare le lacune nelle conoscenze e spiegare chiaramente l'attività e l'obiettivo dell'utente. Potresti non pensare che uno sviluppatore debba scrivere requisiti, ma se riesci a trovare uno sviluppatore che sia anche un buon comunicatore e un buon scrittore, in pratica hai un analista aziendale che comprende le complessità dello sviluppo del software, che è meglio che avere un analista di business questo non comprende la reale complessità dello sviluppo del software (e ce ne sono molti in giro).

Perché?

Karl Weigers una volta ha scritto che se ti mancano i requisiti, non importa quanto tu esegua il resto del progetto, sei maggiormente a rischio di fallimento (e questo è molto più lieve di lui). Una buona specifica dei requisiti non deve essere monolitica (anche se il costo del fallimento è la perdita di vite umane, allora forse potrebbe essere necessario) e una buona avrà tutti, non solo i programmatori, ma anche analisti, manager, progetti manager, esperti in materia e utenti finali sulla stessa pagina.

Gli sviluppatori esperti sanno che la sinergia tra buona conoscenza del dominio, abilità di programmazione e comunicazione è importante per i progetti software di successo. Un documento sui requisiti (su carta, wiki o qualsiasi mezzo) è una buona parte di questo, non solo per l'inizio del progetto, ma anche per la vita dopo il go-live.

Qualsiasi documentazione scritta in linguaggio naturale è suscettibile di ambiguità. Il codice che è ben scritto e ben commentato può ridurre l'ambiguità totalmente o quasi del tutto. Quindi, dovrebbe essere una combinazione di codice con commenti e le specifiche utilizzate per scrivere il codice.