Cette section du chapitre ne traite pas les détails de l'organisation
de la documentation dans la norme peardoc,
mais de la façon d'organiser la documentation logiquement.
Premièrement, chaque package résoud un problème.
Quel est ce problème?
Essayer de faire comprendre quelles prétentions
vos utilisateurs ne devraient pas
avoir à propos du problème
(ils ne doivent pas réaliser que cela est un problème
qui doit être résout).
Par exemple, un package de template
résout à la fois le problème
de la séparation du code et
du design, et celui de séparer la logique de traitement de la
logique d'affichage.
Si possible, expliquez le problème en des termes de façon à ce qu'un
un programmeur débutant puisse comprendre.
Ensuite, comment le package résout-il individuellement
le problème?
C'est le point faible de la plupart des documentations.
Par exemple, il y a beaucoup de moteurs de template.
Tous résolvent le même problème,
mais aucun d'eux ne le fait de la même manière.
Un moteur de template basé sur des bloc n'a aucune logique,
tandis qu'un template comme Smarty définit
un nouveau langage de template complet.
Quelques moteurs de template compilent leurs templates, d'autres pas.
Qu'est-ce qui est unique au sujet de votre paquet?
Est-ce que quelqu'un qui n'a jamais vu le code
peut avoir une bonne idée
de la façon dont il résout
le problème?
Donnez DES exemples!
Commencez tout de suite par des exemples simples
qui montrent les fonctionalités de base
-- ils montreront aux utilisateurs comment commencer
rapidement à employer le package.
Des exemples plus complexes aideront les utilisateurs
à la compréhension des façons
avançées d'employer le package.
Si votre paquet expose les interfaces complexes
ou les constantes multiples
qui ne peuvent pas être entièrement expliquées
dans un ou deux exemples (ce qui est très probable),
ne manquez pas de les expliquer complètement dans la documentation.
Documentez toutes les interfaces que les utilisateurs doivent employer,
comme une base de données DSN,
les arguments pour les applications ligne de commande,
le contenu de dossier de configuration,
ou n'importe quel autre élément qui ne soit pas du code.
Pour finir, peaufinez votre documentation.
Si possible, faites-là relire à une personne qui n'est pas au
courant de votre projet.
Ils remarqueront les hypothèses que vous avez oubliées.
