Man page HOWTO: Quelques évidences à propos de la documentation

1. Quelques évidences à propos de la documentation

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.