Para editar la documentación, normalmente no debería usar editores XML formales. Dichos editores normalmente autoformatean los documentos existentes para ajustarlos a sus propios estándares y/o no siguen estrictamente el estándar docbook. Como ejemplos, los hemos visto eliminar las etiquetas CDATA, cambiar la separación de 4 espacios por tabulaciones o 2 espacios, etc.

Las directrices de estilo se escribieron en gran parte para ayudar a los traductores a reconocer las líneas que han cambiado usando herramientas normales de diff. El autoformato dificulta este proceso.

Las buenas imágenes y diagramas pueden mejorar la legibilidad y la comprensión. Úselas siempre que ayuden a lograr estos objetivos. Las imágenes deben colocarse en el directorio documentation/manual/en/figures/, y nombrarse según el identificador de la sección en la que aparecen.

Busque buenos casos de uso enviados por la comunidad, especialmente los publicados en comentarios de propuestas o en alguna de las listas de correo. Los ejemplos suelen ilustrar el uso mucho mejor que la narrativa.

Al escribir sus ejemplos para incluirlos en el manual, siga todos los estándares de codificación y de documentación.

El manual está pensado para ser una guía de referencia para el uso por parte del usuario final. No se desea replicar la documentación phpdoc de componentes y clases de uso interno, y la narrativa debe centrarse en el uso, no en el funcionamiento interno. En cualquier caso, por el momento, nos gustaría que los equipos de documentación se centraran en traducir el manual en inglés, no los comentarios phpdoc.

Enlace a otras secciones del manual o a fuentes externas en lugar de recrear la documentación.

Para enlazar a otras secciones del manual puede usarse la etiqueta <link> (a la que debe proporcionar un texto de enlace).

<para>
    "Link" links to a section, using descriptive text: <link
        linkend="doc-standard.recommendations.links">documentation on
        links</link>.
</para>

Para enlazar a un recurso externo, use <ulink>:

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