+
+ RecommendationsUse editors without autoformatting+ 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. + +Use Images+ 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. + +Use Case Examples+ 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. + +Avoid Replicating phpdoc Contents+ 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. + +Use Links+ 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 the + <link> tag (to which you must provide link text). + + +
+ To link to an external resource, use <ulink>: + + +
+ +
|
+ + + | +