Come si può migliorare il processo di creazione e manutenzione della documentazione?

4

So che è una domanda molto soggettiva, ma questa è una sezione di Ingegneria del Software in cui non ho visto alcun miglioramento in termini di come possiamo farlo in un modo migliore. Immagino che ogni programmatore faccia documentazione con qualche frustrazione, ma quando lavoro ritengo che sia lo strumento più importante per me. In che modo il processo di creazione e manutenzione della documentazione può essere svolto in modo migliore?

    
posta gizgok 16.02.2011 - 14:20
fonte

1 risposta

6

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.
risposta data 16.02.2011 - 15:09
fonte

Leggi altre domande sui tag