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.

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.

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.

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.

Créez des liens vers les autres sections ou des ressources externes plutôt que de tout réécrire.

Les liens vers d'autres sections du manuel peuvent se faire avec <link> (pour lequel vous devez fournir le nom du lien).

<para>
    "Link" crée un lien vers une section, et utilise un titre explicite : <link
        linkend="doc-standard.recommendations.links">documentation sur la créer de liens</link>.
</para>

Pour créer un lien vers une ressource externe utilisez l'élément <ulink> :

<para>
    Le site du <ulink url="http://framework.zend.com/">Zend Framework</ulink>.
</para>