Recommendations

Utilisez un éditeur sans formatage automatique

Pour éditer la documentation, vous ne devriez pas utiliser un éditeur XML classique. Ces éditeurs formattent pour la plupart automatiquement les documents pour s'adapter à leurs propres standards et/ou ne suivent pas strictement les recommandations du docbook. Par exemple, nous en avons vu certains d'entre eux supprimer l'élément CDATA, remplacer 4 espaces par des tabulations, ou 2 espaces, etc.

Ces recommandations ont été écrites en grande partie afin d'aider les traducteurs à déterminer les changements en utilisant la commande diff. Le formatage automatique rend cette opération plus difficile.

Utilisez des images

Les images et les diagrammes peuvent améliorer la lisibilité et la compréhension. Utilisez les chaque fois qu'ils le permettent. Les images devrait être placées dans le répertoire documentation/manual/en/figures/, et nommées juste après l'identifiant de la section qui les concerne.

Utilisez des cas d'utilisations

Cherchez de bons cas d'utilisation soumis par la communauté, particulièrement ceux des commentaires dans les propositions ou encore sur l'une des liste de discussion. Un exemple vaut mieux qu'un long discours.

Lorsque vous écrivez des exemples à inclure dans le manuel, suivez les conventions de codages ainsi que les recommandations pour la documentation.

Évitez de répéter le contenu des phpdoc

Ce manuel a pour objectif d'être une référence pour l'utilisateur final. Recopier la documentation phpdoc pour expliquer le fonctionnenement interne des composants et des classes n'est pas souhaité, l'accent devrait être mis sur l'utilisation. Dans tous les cas, nous souhaiterions que l'équide de documentation se concentre sur la traduction du manuel anglais, et non pas les commentaires phpdoc.

blog comments powered by Disqus