1. DocBook XML
  2. Conseil pour la
    documentation

Conseils pour une bonne documentation

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.

  1. 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.

  2. 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?

  3. 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.

  4. 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.

  5. 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.

Le format DocBook XML (Previous) Le fichier de définition de package package.xml (Next)
Last updated: Sun, 29 Aug 2010 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

There are no user contributed notes for this page.