Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History

Help Wanted

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.

We are using the Mozilla Style Guide. Please read. Exceptions noted below.

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.

ZF Documentation Philosophy

"Just Fix It!" versus "Serious Issues"

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.

Use editors without autoformatting

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.

Use Images

Good images and diagrams can improve readability and help everyone understand the text in the manual.

Use Case Examples

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

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).

Incorporating Examples and Suggestions from the Community

If the contributions are more than about 1 or 2 lines of code, we probably need a CLA. We should follow fair use conventions.

Avoid replicating phpdoc contents

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.

DocBook Conventions

DocBook: The Definitive Guide

Using CDATA around PHP code

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 line length

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.

Make links

Internal links:

  • using xref: '<xref linkend="section.name" />'
  • using link: '<link linkend="section.name">Something describing the link</link>'

External links:

  • using ulink: '<ulink url="http://framework.zend.com">Zend Framework</link>'

Exceptions to the Mozilla Style Guide

Filenames are Lowercase.

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.

Use Subfolders

Please add examples here.

Character Sets

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.

Authors

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.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.