Skip to end of metadata
Go to start of metadata

<p><strong>Help Wanted</strong></p>

<p>We would like to list a few basic, simple standards and conventions that you believe would make it <strong>easier</strong> for the documentation teams to keep consistent.</p>

<p><a href="">We are using the Mozilla Style Guide. Please read. Exceptions noted below.</a></p>

<p>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.</p>

<h1>ZF Documentation Philosophy</h1>

<h2>"Just Fix It!" versus "Serious Issues"</h2>

<p>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.</p>

<p>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.</p>

<h2>Use editors without autoformatting</h2>

<p>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.</p>

<h2>Use Images</h2>

<p>Good images and diagrams can improve readability and help everyone understand the text in the manual.</p>

<h2>Use Case Examples</h2>

<p>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.</p>

<h2>Code Examples</h2>

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

<h2>Incorporating Examples and Suggestions from the Community</h2>

<p>If the contributions are more than about 1 or 2 lines of code, we probably need a CLA. We should follow <a href="">fair use conventions</a>.</p>

<h2>Avoid replicating phpdoc contents</h2>

<p>phpdoc documentation is generated automatically from comments in the source code.<br />
Only APIs of components meant to be directly used by end ZF developers need translation.<br />
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.</p>

<h1>DocBook Conventions</h1>

<h2><a href="">DocBook: The Definitive Guide</a></h2>

<h2>Using CDATA around PHP code</h2>

<p>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., "<code><</code>" and "<code>></code>"). For only PHP code, PHP tags are not required. See the following example DocBook excerpts:</p>

<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
<programlisting role="php"><![CDATA[
require_once 'Zend/Acl.php';
$acl = new Zend_Acl();

<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
For example, if we assign access controls to <code><Unable to render embedded object: File ([CDATA[$acl->newsletters]]]]><) not found.[CDATA[></code>,
then descendant ACOs such as <code><Unable to render embedded object: File ([CDATA[$acl->newsletters->archive]]]]><) not found.[CDATA[></code> and
<code><Unable to render embedded object: File ([CDATA[$acl->newsletters->pending]]]]><) not found.[CDATA[></code> inherit access controls from the
parent ACO, <code><Unable to render embedded object: File ([CDATA[$acl->newsletters]]]]><) not found.[CDATA[></code>, despite that they have not been
specifically defined for either child ACO.

<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
Zend_Acl provides a tree-based structure to which multiple 'areas' (also known as ACOs)
can be added. These 'areas' within the ACL can be assigned either generic or specific
'actions' (known as Contexts) that determine access privileges for user-defined 'groups'
(or AROs). These actions are assigned to ACOs ad hoc when calling <code>allow()</code>
or <code>deny()</code>.

<h2>Limit line length</h2>

<p>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.</p>

<h2>Make links</h2>

<p>Internal links:</p>
<ul class="alternate">
<li>using xref: '<xref linkend="" />'</li>
<li>using link: '<link linkend="">Something describing the link</link>'</li>

<p>External links:</p>
<ul class="alternate">
<li>using ulink: '<ulink url=";&gt;Zend Framework</ulink>'</li>

<h1>Exceptions to the Mozilla Style Guide</h1>

<h3>Filenames are Lowercase.</h3>

<p>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.</p>

<h3>Use Subfolders</h3>

<p>Please add examples here.</p>

<h3>Character Sets</h3>

<p>Use the ISO-8859-1 aka. Latin-1 character encoding for the English manual.</p>

<p>Use UTF-8 for the translations. UTF-8 is natively supported by this wiki.</p>


<p>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: </p>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[[~username]]]></ac:plain-text-body></ac:macro>
<p> to link directly to the author's wiki profile. </p>

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Apr 21, 2012

    <p>I am starting to learn PHP now and think I missed some inportants points, I will save your wiki for future reference because there is some tips that will be useful for foture reference.</p>


    <p><a class="external-link" href=""></a></p>