Diverse persone apprezzano diversi tipi di documentazione. Ad esempio, non trovo affatto utili i diagrammi UML di un intero progetto. Non scrivere documenti enormi che nessuno legge e che sono difficili da mantenere. Cerca di mantenere la documentazione per gli sviluppatori il più vicino possibile al codice.
La quantità minima di documentazione è una panoramica in stile README che descrive come testare e distribuire il progetto. A volte questo è ovvio (ad esempio se la lingua o l'ecosistema ha forti convenzioni), ma spesso non lo è.
Inoltre, considera di fornire una rapida panoramica della struttura del progetto, non necessariamente a livello di classi, ma a livello di directory. Per esempio. potrebbe già essere utile dire "qui ci sono i nostri modelli, qui ci sono i nostri controllori, qui i nostri test, qui una libreria da integrare con il nostro fornitore di servizi di pagamento, e qui alcune varie funzioni di supporto." Un diagramma del pacchetto UML può o non può aiuto per questo. Il punto di questa panoramica è di dire a un nuovo sviluppatore dove cercare.
Oltre a una panoramica, è utile se le conoscenze implicite sulla base di codice diventano esplicite. Per esempio. le funzioni potrebbero avere varie precondizioni e garanzie. Aiuta a documentare ciò nel codice sorgente. Non devi passare due settimane a documentare meticolosamente ogni funzione. Invece, la regola del boy scout potrebbe aiutare: lasciare una funzione migliore di quella che hai trovato. Se stai lavorando su una funzione in ogni caso, attualmente comprendi il suo comportamento. Prenditi un minuto per riversare questa comprensione in un commento del doc.
Infine, considera cosa succede se uno sviluppatore si chiude o viene rilasciato. Idealmente c'è un periodo di preavviso contrattualmente garantito. Mentre potrebbe non essere bello avere questo sviluppatore che lavora su nuove funzionalità durante il periodo di preavviso, un ottimo uso delle settimane rimanenti può essere quello di scrivere documenti. I periodi di preavviso possono avvantaggiare sia l'azienda che il dipendente. Se vivi in una giurisdizione in cui non sono legalmente richiesti, prendi in considerazione la possibilità di negoziare emendamenti contrattuali: mentre tutti sono sostituibili, avere un po 'più planabilità attorno a tale sostituzione può aiutarti a evitare un'improvvisa perdita di conoscenza organizzativa.