Perché scriviamo la documentazione? Domanda stupida. Perché vogliamo che le altre persone siano in grado di usare il nostro programma, la nostra libreria di funzioni o qualsiasi altra cosa avessimo scritto per metterla a disposizione. Ma scrivere documentazione non si riduce solo a questo:
La documentazione deve essere accessibile; se venisse rintanata in qualche posizione non standard, dove gli strumenti per gestire la documentazione non possono trovarla, come potrebbe servire allo scopo?
La documentazione deve essere affidabile e accurata; non c'è nulla di più irritante di un programma che si comporta diversamente da come è descritto. In casi del genere gli utenti possono semplicemente mandare l'autore a quel paese, ma possono anche arrivare a spedirgli email cariche d'odio; infine scaraventeranno qualunque suo lavoro alle ortiche, col fermo intento di non installare mai più qualunque cosa venga scritto da un tale balordo.
Il modo tradizionale e ben noto per accedere alla documentazione su UNIX è attraverso il comando man(1). Questo HOWTO descrive le procedure per scrivere una pagina di manuale che possa essere elaborata correttamente dagli strumenti per il trattamento della documentazione. Tra questi strumenti, i più importanti sono man(1), xman(1x), apropos(1), makewhatis(8) e catman(8). Il compito di garantire l'affidabilità e l'accuratezza delle informazioni spetta, ovviamente, tutto a voi; ma proseguendo nella lettura troverete comunque qualche idea che potrà aiutarvi a evitare alcuni errori tra quelli commessi più di frequente.