We would like to list a few basic, simple standards and conventions that you believe would make it easier for the documentation teams to keep consistent.
Whenever anyone finds something they do not agree with in the Mozilla Style Guide, we should discuss on the mail list, and possibly add an exceptions or clarification to this wiki page.
When a serious or non-trivial problem is found, report it as a documentation problem or improvement in our issue tracker. This allows helps the community discuss possible ways to improve or solve the problem. If you are confident of a solution or edit, just do it. Editors will review later.
However, we all need to accomodate and tolerate occasional mistakes in a friendly way, so that we can all get more work done quicker and avoid too much "red tape" beauracracy. If you make 10 edits and only 1 has a problem, but you make 10 edits in a week this is good. Waiting for approvals and making the same 10 edits in a month is not as good, and probably a little frustrating if the edits are not that hard.
For editing the documentation you should not use xml editors. They normally autoformat existing documents to fit their needs. And they do not follow the docbook standard. For example they can erase the cdata tags, they can change the 4 spaces seperation to tabs or 2 spaces and many many more.
Good images and diagrams can improve readability and help everyone understand the text in the manual.
Look for good use cases and example submitted by the community, especially those posted in emails to the mailing lists or in comments on wiki pages.
Code examples in the documentation should follow the ZF coding standard. For example the "?>" closing tag should not be used. In fact, the documentation should clarify the reasons why it should not be used (avoids problems with whitespace after the closing tag causing the browser to see "blank" pages).
If the contributions are more than about 1 or 2 lines of code, we probably need a CLA. We should follow fair use conventions.
phpdoc documentation is generated automatically from comments in the source code.
Only APIs of components meant to be directly used by end ZF developers need translation.
Replicating all the phpdoc documentation for internal-use components and classes is not wanted. In any case, at this time, we would like the documentation teams to focus on translating the English manual, not the phpdoc pages for the handful of components with public-facing API's.
In DocBook, we use the <programlisting> tag to wrap PHP code examples. For inline PHP variable names, functions and methods, the <code> tag may be used to indicate that the inline content contains code. Within <programlisting> one should always use the CDATA tag to indicate that arbitrary character data is used, though one may omit for brevity the CDATA tag within <code> tags that do not contain special characters (e.g., "<" and ">"). For only PHP code, PHP tags are not required. See the following example DocBook excerpts:
Limit the length per line to 100 characters. You can extend the 100 characters length when you have a no seperating whitespace within a link for example.
- using xref: '<xref linkend="section.name" />'
- using link: '<link linkend="section.name">Something describing the link</link>'
- using ulink: '<ulink url="http://framework.zend.com">Zend Framework</link>'
Filenames should follow conventions of similar or related files in the ZF. Each word in source files containing ZF classes begin a capital letter. All other files normally would contain only lowercase letters.
Please add examples here.
Use the ISO-8859-1 aka. Latin-1 character encoding for the English manual.
Use UTF-8 for the translations. UTF-8 is natively supported by this wiki.
Each document's author should be listed at the top. If it is a communal document, or an index, it's ok to leave the author off. If it is a document with real content, it should list a way of contacting the author and providing feedback. Anonymity is bad. Use the wiki syntax:to link directly to the author's wiki profile.