Non c'è un proiettile d'argento. Come altri aspetti della programmazione, devi decomporre il problema e affrontare un'area alla volta.
Ecco alcune idee che possono (nella mia esperienza) essere utili:
Riduci la necessità di documentazione
- Ci sono spesso modi migliori di comunicare che attraverso documenti, ad es. faccia a faccia
- Identifica quali documenti hanno poco valore e smetti di produrli
- I programmi ben strutturati richiedono meno documentazione
- Utilizza nomi di variabili significativi ecc. per ridurre la necessità di documentare
- Utilizza saggiamente i commenti sul codice
- Collegati agli articoli web appropriati piuttosto che riprodurli nella tua documentazione
Genera documentazione
- I diagrammi delle classi possono spesso essere generati dal codice e quindi annotati
- I diagrammi E-R possono essere spesso generati da un database
- Utilizza strumenti come javadoc per documentare le API
Scegli gli strumenti giusti
- Se vuoi che la documentazione sia sviluppata in modo collaborativo, usa qualcosa come un Wiki.
- Se vuoi che la documentazione sia mantenuta al passo con il codice sorgente, mantieni la documentazione nel controllo del codice sorgente.
- Considera i vantaggi di una soluzione integrata di monitoraggio dei bug / knowledge base / fonte
- Le immagini possono parlare più di mille parole. Usa gli strumenti di diagrammi ecc.
- Utilizzare una lavagna interattiva nelle riunioni e conservare una copia delle cose scritte sulla lavagna (o se si utilizza una lavagna normale, scattare una foto).
Scegli il mezzo giusto
- Invece di scrivere tutto, prendi in considerazione l'uso di registrazioni video o audio (ottimo sia per i documenti di acquisizione dei requisiti che per i documenti degli utenti finali) e per le fotografie.
- Archivia email relative al progetto
Scegli la qualità giusta
- Non tutti i documenti devono essere lucidati. A volte, uno schizzo approssimativo è sufficiente finché tutti possono trovarlo quando è necessario.
Scegli le persone giuste
Le persone dovrebbero documentare in base al dominio delle loro competenze. Ad esempio, gli utenti dovrebbero scrivere la documentazione dell'utente (dopotutto, gli utenti comprendono meglio i problemi aziendali risolti dal software e esprimono la loro comprensione del software in termini commerciali).
Crea la cultura giusta
A volte, i problemi di documentazione sono davvero problemi con le persone:
- Se ritieni che la documentazione sia il modo migliore per conservare la conoscenza nella tua azienda, il vero problema potrebbe essere quello della fidelizzazione del personale.
- Se senti il bisogno di documentare ogni dettaglio su chi ha fatto cosa, il vero problema potrebbe essere che la tua organizzazione favorisce una cultura della colpa.
- Se senti il bisogno di documentare come mezzo per condividere la conoscenza, puoi trarre beneficio dal scoprire perché le persone non si limitano a parlarsi.
- Se stai documentando ogni dettaglio di ogni piccola decisione, potresti scoprire che stai lavorando in un ambiente a basso rischio.