For editing the documentation, typically you should not use formal XML editors. Such editors normally autoformat existing documents to fit their own standards and/or do not strictly follow the docbook standard. As examples, we have seen them erase the CDATA tags, change 4 space separation to tabs or 2 spaces, etc.

The style guidelines were written in large part to assist translators in recognizing the lines that have changed using normal diff tools. Autoformatting makes this process more difficult.

Good images and diagrams can improve readability and comprehension. Use them whenever they will assist in these goals. Images should be placed in the documentation/manual/en/figures/ directory, and be named after the section identifier in which they occur.

Look for good use cases submitted by the community, especially those posted in proposal comments or on one of the mailing lists. Examples often illustrate usage far better than the narrative does.

When writing your examples for inclusion in the manual, follow all coding standards and documentation standards.

The manual is intended to be a reference guide for end-user usage. Replicating the phpdoc documentation for internal-use components and classes is not wanted, and the narrative should be focussed on usage, not the internal workings. In any case, at this time, we would like the documentation teams to focus on translating the English manual, not the phpdoc comments.

Link to other sections of the manual or to external sources instead of recreating documentation.

Linking to other sections of the manual may be done using either the <xref> tag (which will substitute the section title for the link text) or the <link> tag (to which you must provide link text).

To link to an external resource, use <ulink>: