Documenti automatici

Nelle fasi di implementazione si iniziano a scrivere i sorgenti che compongono il sistema. Questi sorgenti contengono un'enome quantità di informazioni, alcune delle quali sono utili in sè altre che richiederebbero un minimo di documentazione allegata.

Se immaginiamo che i sorgenti del sistema possano costituire la base di documenti di dettaglio o di riferimento, ci rendiamo immediatamente conto che una tecnica felice sarebbe quella da estrarre la documentazione dai sorgenti medesimi. Per far ciò serve un sistema in grado di:

• Reperire le entità da documentare, tramite un eseme diretto del sorgente oppure con l'ausilio di markup che possano semplificare la logica della scansione.
• Allegare a tali entità note e commenti reperiti nel sorgente. Anche in questo caso è necessario un sistema di markup.

I vantaggi della documentazione automatica sono:

• E' completa, o per lo meno il grado di completezza è misurabile.
• E' facilmente manutenibile, il medesimo programmatore che modifica il sorgente può contestualmente modificare la documentazione.
• E' facile individuare i componenti non documentati.

Gli svantaggi della documentazione automatica sono:

• E' prodotta in modo molto frammentario.
• Tende ad essere breve e sintetica.
• Non è facile includerla in documenti stampati in quanto i diversi testi sono spesso scollegati tra loro.
• Se da un canto è facile rivederla quando si ha il sorgente in mano, è difficile correggerla quando bisogna andare a caccia del sorgente.

Il vantaggio più importante della documentazione automatica è che copre tutta la struttura del sistema, è in grado cioè di fornire una mappa completa. Anche una documentazione automatica povera limitata al nome e alla descrizione breve di ciascuno entità fornisce una quantità insospettata di informazioni:

1. Comunica rapidamente cosa è disponibile e cosa non lo è.
2. Per una persona che non conosce il sistema ne definisce i limiti.
3. Il solo fatto di categorizzare in modo omogeneo tale elenco aggiunge moltissimo al contenuto informativo del medesimo. Ad esempio un sotto-sistema è già ben descritto con l'elenco dei suoi componenti:
1. Elenco delle voci di menu.
2. Elenco delle mappe video.
3. Elenco delle stampe.
4. Elenco delle procedura batch,

Purtroppo la documentazione automatica non può essere prodotta dall'eseme dei sorgenti così come sono, senza bisogno di alcun intervento manuale per aggiungere commenti o simili nei sorgenti. Questa attività di arrichimento può diventare molto costosa e va attentamente valutata. E' importante gestire la documentazione automatica a livelli:

1. Il primo livello è quello del censimento. Tutte le entità vengono identificate, viene stabilito il sistema di nomenclatura, vengono predisposti i tools per produrre gli elenchi composti dal binomio nome e descrizione.
2. Il secondo livello è la categorizzazione delle entità. Tipicamente realizzata assegnandole a sistemi e sotto-sistemi.
3. Il terzo livello è l'arrichimento delle singole entità.

La cosa importante da osservare è che i primi due step prevedono un impegno limitato anche a fronte dei sistemi grossi e complessi. Ma il completamento di questi primi due step offre innumerevoli vantaggi:

1. Identifica tutte le entità. Queste possono essere citate, iniziando a formare il web che in fondo è il cuore del sistema di documentazione.
2. Permette di gestire, in modo ordinato, il processo di arrichimento, anche diluendolo nel tempo.
3. Permette di gestire in modo completo la documentazione che si deve produrre via via che il sistema evolve nel tempo.

Una volta prodotta la documentazione automatica ha la stessa dignità della documentazione preparata manualmente e le stesse possibilità di formattazione.