Pourquoi écrivons-nous une documentation ? C'est une
question bête. Parce que nous voulons que d'autres personnes
puissent utiliser notre programme, notre fonction dans une librairie
ou quoi que ce soit que nous avons écrit et rendu disponible. Mais
écrire une documentation n'est pas suffisant :
- la documentation doit être accessible. Si elle est cachée à
un endroit non standard où les outils de recherche relatifs à la
documentation ne la trouveront pas, comment peut-elle
remplir son rôle ?
- la documentation doit être fiable et précise. Il n'y a rien de
plus irritant qu'un programme se comportant différemment
de ce qui est écrit dans sa documentation. Les
utilisateurs vous maudiront, vous enverront des courriers
d'insulte, puis rejetteront à jamais tout autre travail
venant de vous.
La méthode traditionnelle pour accéder à la documentation sous
UNIX fait appel à la commande man(1). Ce HOWTO décrit
ce que vous devez faire pour écrire une page de manuel qui
sera correctement traitée par les outils prévus à cet effet,
dont les plus importants sont man(1), xman(1x),
apropos(1), makewhatis(8) et
catman(8).
La qualité et la véracité des informations sont, bien sûr, de votre
ressort. Malgré tout, vous trouverez dans ce guide quelques idées qui
vous permettront d'éviter certains pièges courants.
|