compared with
Current by Mickael Perraud
on Apr 18, 2009 05:05.

Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (85)

View Page History
*Help Wanted*
<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 *easier* <strong>easier</strong> for the documentation teams to keep consistent.</p>

[We <p><a href="http://www.mozilla.org/contribute/writing/guidelines">We are using the Mozilla Style Guide. Please read. Exceptions noted below.|http://www.mozilla.org/contribute/writing/guidelines] 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>ZF Documentation Philosophy</h1>

h2. "Just Fix It!" versus "Serious Issues"
<h2>&quot;Just Fix It!&quot; versus &quot;Serious Issues&quot;</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" &quot;red tape&quot; 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>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>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>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>Code Examples</h2>

<p>Code examples in the documentation should follow the ZF coding standard. For example the "?>" &quot;?&gt;&quot; 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). &quot;blank&quot; pages).</p>

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

If the contributions are more than about 1 or 2 lines of code, we probably need a CLA. We should follow [fair use conventions|http://www.copyright.gov/fls/fl102.html].
<p>If the contributions are more than about 1 or 2 lines of code, we probably need a CLA. We should follow <a href="http://www.copyright.gov/fls/fl102.html">fair use conventions</a>.</p>

h2. Avoid replicating phpdoc contents
<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>DocBook Conventions</h1>

h2. [DocBook: The Definitive Guide|http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html]
<h2><a href="http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html">DocBook: The Definitive Guide</a></h2>

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

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:
<p>In DocBook, we use the &lt;programlisting&gt; tag to wrap PHP code examples. For inline PHP variable names, functions and methods, the &lt;code&gt; tag may be used to indicate that the inline content contains code. Within &lt;programlisting&gt; 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 &lt;code&gt; tags that do not contain special characters (e.g., &quot;<code>&lt;</code>&quot; and &quot;<code>&gt;</code>&quot;). For only PHP code, PHP tags are not required. See the following example DocBook excerpts:</p>

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

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

{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
<para>
Zend_Acl provides a tree-based structure to which multiple 'areas' (also known as ACOs)
or <code>deny()</code>.
</para>
{code}
]]></ac:plain-text-body></ac:macro>

h2. Limit line length
<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>Make links</h2>

Internal links:
- using xref: '<xref linkend="section.name" />'
- using link: '<link linkend="section.name">Something describing the link</link>'
<p>Internal links:</p>
<ul class="alternate">
<li>using xref: '&lt;xref linkend=&quot;section.name&quot; /&gt;'</li>
<li>using link: '&lt;link linkend=&quot;section.name&quot;&gt;Something describing the link&lt;/link&gt;'</li>
</ul>

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

h1. Exceptions to the Mozilla Style Guide
<p>External links:</p>
<ul class="alternate">
<li>using ulink: '&lt;ulink url=&quot;http://framework.zend.com&quot;&gt;Zend Framework&lt;/ulink&gt;'</li>
</ul>

h3. 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.
<h1>Exceptions to the Mozilla Style Guide</h1>

h3. Use Subfolders
<h3>Filenames are Lowercase.</h3>

Please add examples here.
<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. Character Sets
<h3>Use Subfolders</h3>

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

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

h3. Authors
<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>

<h3>Authors</h3>

<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: {code}[~username]{code} to link directly to the author's wiki profile. </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>