Les pages de références doivent obéir à des règles construction standard. Ainsi, un utilisateur pourra trouver l'information qu'il souhaite de manière plus rapide et cela encourage également les rédacteurs à documenter tous les aspects relatifs à une commande. Cette consistance n'est pas uniquement souhaitée pour les pages de références PostgreSQL™, mais également pour les pages de références fournies par le système d'exploitation et les autres paquetages. C'est pour cela que les règles suivantes ont été développées. Elles sont pour la plupart consistantes avec d'autres règles similaires établies par les différents systèmes d'exploitation.
Les pages de référence qui décrivent les commandes exécutables doivent contenir les sections suivantes dans l'ordre. Les sections qui ne sont pas applicables peuvent être omises. Des sections de premier niveau ne pourront être utilisées que dans des circonstances particulières ; dans la plupart des cas, les informations devant y figurer pourront appartenir à la section « Usage ».
Cette section est générée automatiquement. Elle contient le nom de la commande et une courte phrase résumant sa fonctionnalité.
Cette section contient le schéma syntaxique de la commande. Le synopsis ne doit en général pas lister toutes les options de la commande, cela sera fait juste au dessous. À la place, il est important de lister les composantes majeures de la ligne de commande comme par exemple où les fichiers d'entrée et sortie se trouvent.
Plusieurs paragraphes décrivant ce que permet de faire la commande.
Une liste décrivant chacune des options de la ligne de commande. S'il y a beaucoup d'options, il sera possible d'utiliser des sous-sections.
Si le programme utilise 0 lors d'un succès et une valeur différente de 0 pour un échec, vous devez le documenter. S'il y a une signification particulière au code de retour différent de zéro, décrivez-les ici.
Décrivez ici tout subtilité ou interface de lancement du programme. Si le programme n'est pas interactif, cette section peut être omise. Dans les autres cas, cette section est un fourre-tout pour les fonctionnalités disponibles lors de l'utilisation du programme. Utilisez des sous-sections si cela est approprié.
Listez ici toute variable d'environnement qui pourrait être utilisée. Efforcez-vous de ne rien omettre même si des variables vous semblent triviales au premier coup d'œil comme SHELL qui pourrait être d'un quelconque intérêt pour l'utilisateur.
Listez tout fichier que le programme pourrait accéder, même implicitement. Ne listez pas les fichiers d'entrée ou de sortie ayant été spécifiés en ligne de commande, mais plutôt les fichiers de configuration, etc.
Expliquez ici tout sortie inhabituelle que le programme pourrait créer. Retenez-vous cependant de lister tous les messages d'erreur possibles. Cela représente beaucoup de travail et n'est pratiquement jamais utilisé. Mais si, par exemple, les messages d'erreurs ont un format particulier pouvant être traité par l'utilisateur, cette section est le bon endroit pour en décrire la composition.
Tout ce qui ne peut être contenu dans les autres sections peut être placé ici. Plus particulièrement, les points concernant les bogues, les largesses d'implémentations, la sécurité et la compatibilité pourront être abordés ici.
Les exemples.
S'il y a eu des échéances majeures dans l'histoire du programme vous pouvez les lister ici. Typiquement, cette section peut être omise.
Les références croisées, listées dans l'ordre suivant : pages de référence vers d'autres commandes PostgreSQL™, pages de références de commmandes SQL de PostgreSQL™, citation des manuels PostgreSQL™, autres pages de référence (c'est-à-dire système d'exploitation, autres paquetages), autres documentations. Les éléments dans un même groupe sont listés dans l'ordre alphabétique.
Les pages de référence décrivant les commandes SQL doivent contenir les sections suivantes : Nom, Synopsis, Description, Paramètres, Sorties, Notes, Exemples, Compatibilité, Historique, Voir aussi. La section Paramètres est identique à la section Options mais elle offre plus de libertés sur lesquelles des clauses peuvent être listées. La section Sorties n'est seulement nécessaire que si la commande renvoie quelque chose d'autre qu'un complément de commande par défaut. La section Compatibilité doit expliquer en quelle mesure une commande se conforme au(x) standard(s) SQL, ou avec quel autre système de gestion de base de données elle est compatible. La section Voir aussi des commandes SQL doit lister les commandes SQL avant de faire des références croisées vers les programmes.
Écriture de la documentation