Para editar a documentação, normalmente você não deve usar os editores XML clássicos. Esses editores geralmente formatam automaticamente os documentos existentes para que se adaptem as suas próprias normas e/ou não seguem rigorosamente o padrão docbook. Como exemplos, já os vimos apagar as tags CDATA, substituírem 4 espaços por tabs ou 2 espaços etc.

Estas diretrizes foram escritas em grande parte para auxiliar os tradutores no reconhecimento das linhas que foram alteradas usando as ferramentas de diff normais. A formatação automática torna esse processo mais difícil.

Boas imagens e diagramas podem melhorar a legibilidade e a compreensão. Use-as sempre que ajudarem nesses objetivos. Imagens devem ser colocadas no diretório documentation/manual/en/figures/, e nomeadas após o identificador de seção em que lhes diz respeito.

Procure por bons casos de uso apresentados pela comunidade, especialmente aqueles que são publicados nos comentários de sugestão ou nas listas de discussão. Os exemplos frequentemente ilustram a utilização muito melhor do que todo o texto.

Ao escrever seus exemplos para inclusão no manual, siga todas as normas de codificação e de documentação.

O manual pretende ser um guia de referência para a utilização do usuário final. A duplicação da documentação de phpdoc para componentes e classes de uso interno não é desejada, e a documentação deve estar focada na utilização e não no funcionamento interno. Em qualquer caso, neste momento, gostaríamos que as equipes de documentação se concentrassem na tradução do manual em inglês, e não nos comentários de phpdoc.

Crie links para outras seções do manual ou para fontes externas em vez de recriar documentação.

Os links para outras seções do manual podem ser feitos usando o elemento <link> (para o qual você deve fornecer o nome do link).

<para>
    "Link" cria um link para uma seção, usando um texto descritivo: <link
        linkend="doc-standard.recommendations.links">documentação sobre os
        links</link>.
</para>

Para criar um link para uma fonte externa, use <ulink>:

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