1. Quelques évidences

Contenu de cette section

Pourquoi rédigeons-nous des documentations ? À question stupide, réponse stupide : pour que tout le monde sache utiliser notre programme, notre fonction bibliothèque ou tout autre code de notre cru que nous diffusons dans ce but. Mais la rédaction n'est pas tout :

• la documentation doit être accessible. Si elle est placée en un endroit non standard tel que les outils destinés à son exploitation ne la trouvent pas, comment peut-elle remplir son rôle ?
• la documentation doit être fiable et à jour. Il n'y a rien de plus irritant que de rencontrer un programme se comportant différemment de ce qui est décrit dans son manuel. 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 document décrit les opérations nécessaires pour la rédaction d'une page de manuel qui sera correctement traitée par les outils de formatage prévus à cet effet. Parmi ces outils, les plus importants sont man(1), xman(1x), apropos(1), makewhatis(8) et catman(8).

La qualité et la véracité des informations sont de votre ressort, bien entendu. Malgré tout, vous trouverez dans ce guide quelques idées qui vous permettront d'éviter certains pièges courants.

Chapitre suivant

Table des matières de ce chapitre, Table des matières générale

Début du document, Début de ce chapitre