Esperienza HTML - Arlib32

Circa un'anno fa ci si è posti il problema di rivedere la documentazione delle librerie di sviluppo. Tale documentazione era stata originariamente sviluppata per un prodotto chiamato Norton-guide. Di fatto sulla base di un documento preparato in word 5 e poi tradotto nel formato richiesto dalle Norton Guide.

A questo punto si erano cumulati i notevoli problemi di manutenzione e di obsolescenza.

Io Gabri e Franco abbiamo esaminato delle alternative e abbiamo deciso di creare un progetto seguendo questo schema:

1. Nei programmi e negli header di libreria sarebbero stati aggiunti dei commenti speciali. L'ispirazione per tale impostazione è venuta dalle tecniche di documentazione di Java¹.
2. Una serie di programmi perl avrebbe estratto tali informazioni.
3. I programmi perl combinati con dei template html preparati dalla Gabri² avrebbe permesso la generazione di un'insieme di documenti html collegati tra loro.

Il tutto è stato realizzato in qualche settimana. Da allora circa il 40% della libreria originaria è stata documentata³.

In ogni caso il risultato dei documenti html è eccellente. Molto meglio di quanto non si riesca a fare in notes. Restava però il problema della produzione di documenti stampati.

La libreria risultava in parte documentata all'interno dei sorgenti e in parte documentata tramite files describe.

---

¹ Javadoc.

² Simile all'idea dei files fst.

³ Da me e da Gabri.