Zend Framework Documentation Standard

Overview

Scope

This document provides guidelines for creation of the end-user documentation found within Zend Framework. It is intended as a guide to Zend Framework contributors, who must write documentation as part of component contributions, as well as to documentation translators. The standards contained herein are intended to ease translation of documentation, minimize visual and stylistic differences between different documentation files, and make finding changes in documentation easier with diff tools.

You may adopt and/or modify these standards in accordance with the terms of our license.

Topics covered in Zend Framework’s documentation standards include documentation file formatting and recommendations for documentation quality.

Documentation File Formatting

XML Tags

Each manual file must include the following XML declarations at the top of the file:

1
2
<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->

XML files from translated languages must also include a revision tag containing the revision of the corresponding English-language file the translation was based on.

1
2
3
<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 14978 -->
<!-- Reviewed: no -->

Maximum Line Length

The maximum line length, including tags, attributes, and indentation, is not to exceed 100 characters. There is only one exception to this rule: attribute and value pairs are allowed to exceed the 100 chars as they are not allowed to be separated.

Indentation

Indentation should consist of 4 spaces. Tabs are not allowed.

Tags which are at the same level must have the same indentation.

1
2
3
4
5
<section>
</section>

<section>
</section>

Tags which are one level under the previous tag must be indented with 4 additional spaces.

1
2
3
4
<section>
    <section>
    </section>
</section>

Multiple block tags within the same line are not allowed; multiple inline tags are allowed, however.

1
2
3
4
5
6
7
8
<!-- NOT ALLOWED: -->
<section><section>
</section></section>

<!-- ALLOWED -->
<para>
    <classname>Zend_Magic</classname> does not exist. <classname>Zend\Permissions\Acl</classname> does.
</para>

Line Termination

Line termination follows the Unix text file convention. Lines must end with a single linefeed (LF) character. Linefeed characters are represented as ordinal 10, or hexadecimal 0x0A.

Note: Do not use carriage returns (CR) as is the convention in Apple OS’s (0x0D) or the carriage return - linefeed combination (CRLF) as is standard for the Windows OS (0x0D, 0x0A).

Empty tags

Empty tags are not allowed; all tags must contain text or child tags.

1
2
3
4
5
6
7
<!-- NOT ALLOWED -->
<para>
    Some text. <link></link>
</para>

<para>
</para>

Usage of whitespace within documents

Whitespace within tags

Opening block tags should have no whitespace immediately following them other than line breaks (and indentation on the following line).

1
2
3
<!-- NOT ALLOWED -->
<section>WHITESPACE
</section>

Opening inline tags should have no whitespace immediately following them.

1
2
3
4
5
<!-- NOT ALLOWED -->
This is the class <classname> Zend_Class</classname>.

<!-- OK -->
This is the class <classname>Zend_Class</classname>.

Closing block tags may be preceded by whitespace equivalent to the current indentation level, but no more than that amount.

1
2
3
4
5
6
7
<!-- NOT ALLOWED -->
    <section>
     </section>

<!-- OK -->
    <section>
    </section>

Closing inline tags must not be preceded by any whitespace.

1
2
3
4
5
<!-- NOT ALLOWED -->
This is the class <classname>Zend_Class </classname>

<!-- OK -->
This is the class <classname>Zend_Class</classname>

Multiple line breaks

Multiple line breaks within or between tags are not allowed.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
<!-- NOT ALLOWED -->
<para>
    Some text...

    ... and more text
</para>


<para>
    Another paragraph.
</para>

<!-- OK -->
<para>
    Some text...
    ... and more text
</para>

<para>
    Another paragraph.
</para>

Separation between tags

Tags at the same level must be separated by an empty line to improve readability.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
<!-- NOT ALLOWED -->
<para>
    Some text...
</para>
<para>
    More text...
</para>

<!-- OK -->
<para>
    Some text...
</para>

<para>
    More text...
</para>

The first child tag should open directly below its parent, with no empty line between them; the last child tag should close directly before the closing tag of its parent.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<!-- NOT ALLOWED -->
<section>

    <section>
    </section>

    <section>
    </section>

    <section>
    </section>

</section>

<!-- OK -->
<section>
    <section>
    </section>

    <section>
    </section>

    <section>
    </section>
</section>

Program Listings

The opening <programlisting> tag must indicate the appropriate “language” attribute and be indented at the same level as its sibling blocks.

<para>Sibling paragraph.</para>

<programlisting language="php"><![CDATA[

CDATA should be used around all program listings.

<programlisting> sections must not add linebreaks or whitespace at the beginning or end of the section, as these are then represented in the final output.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<!-- NOT ALLOWED -->
<programlisting language="php"><![CDATA[

$render = "xxx";

]]></programlisting>

<!-- OK -->
<programlisting language="php"><![CDATA[
$render = "xxx";
]]></programlisting>

Ending CDATA and <programlisting> tags should be on the same line, without any indentation.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<!-- NOT ALLOWED -->
    <programlisting language="php"><![CDATA[
$render = "xxx";
]]>
    </programlisting>

<!-- NOT ALLOWED -->
    <programlisting language="php"><![CDATA[
$render = "xxx";
    ]]></programlisting>

<!-- OK -->
    <programlisting language="php"><![CDATA[
$render = "xxx";
]]></programlisting>

The <programlisting> tag should contain the “language” attribute with a value appropriate to the contents of the program listing. Typical values include “css”, “html”, “ini”, “javascript”, “php”, “text”, and “xml”.

<!-- PHP -->
<programlisting language="php"><![CDATA[

<!-- Javascript -->
<programlisting language="javascript"><![CDATA[

<!-- XML -->
<programlisting language="xml"><![CDATA[

For program listings containing only PHP code, PHP tags (e.g., “<?php”, ”?>”) are not required, and should not be used. They simply clutter the narrative, and are implied by the use of the <programlisting> tag.

<!-- NOT ALLOWED -->
<programlisting language="php"<![CDATA[<?php
    // ...
?>]]></programlisting>

<programlisting language="php"<![CDATA[
<?php
    // ...
?>
]]></programlisting>

Line lengths within program listings should follow the coding standards recommendations.

Refrain from using require_once(), require(), include_once(), and include() calls within PHP listings. They simply clutter the narrative, and are largely obviated when using an autoloader. Use them only when they are essential to the example.

Note

Never use short tags

Short tags (e.g., “<?”, “<?=”) should never be used within programlisting or the narrative of a document.

Notes on specific inline tags

classname

The tag <classname> must be used each time a class name is represented by itself; it should not be used when combined with a method name, variable name, or constant, and no other content is allowed within the tag.

1
2
3
<para>
    The class <classname>Zend_Class</classname>.
</para>

varname

Variables must be wrapped in the <varname> tag. Variables must be written using the “$” sigil. No other content is allowed within this tag, unless a class name is used, which indicates a class variable.

1
2
3
4
<para>
    The variable <varname>$var</varname> and the class variable
    <varname>Zend_Class::$var</varname>.
</para>

methodname

Methods must be wrapped in the <methodname> tag. Methods must either include the full method signature or at the least a pair of closing parentheses (e.g., “()”). No other content is allowed within this tag, unless a class name is used, which indicates a class method.

1
2
3
4
5
<para>
    The method <methodname>foo()</methodname> and the class method
    <methodname>Zend_Class::foo()</methodname>. A method with a full signature:
    <methodname>foo($bar, $baz)</methodname>
</para>

constant

Use the <constant> tag when denoting constants. Constants must be written in UPPERCASE. No other content is allowed within this tag, unless a class name is used, which indicates a class constant.

1
2
3
4
<para>
    The constant <constant>FOO</constant> and the class constant
    <constant>Zend_Class::FOO</constant>.
</para>

filename

Filenames and paths must be wrapped in the <filename> tag. No other content is allowed in this tag.

1
2
3
<para>
    The filename <filename>application/Bootstrap.php</filename>.
</para>

command

Commands, shell scripts, and program calls must be wrapped in the <command> tag. If the command includes arguments, these should also be included within the tag.

1
2
3
<para>
    Execute <command>zf.sh create project</command>.
</para>

code

Usage of the <code> tag is discouraged, in favor of the other inline tasks discussed previously.

Notes on specific block tags

title

The <title> tag is not allowed to hold other tags.

1
2
3
4
5
<!-- NOT ALLOWED -->
<title>Using <classname>Zend_Class</classname></title>

<!-- OK -->
<title>Using Zend_Class</title>

Recommendations

Use editors without autoformatting or with configurable formatting

The style guidelines were written in large part to assist translators in recognizing the lines that have changed using normal diff tools.

Many formal XML editors autoformat existing and new documents. Often, this formatting either does not strictly follow the docbook standard, or does not follow the standards outlined in this document. As examples, we have seen them erase the CDATA tags, change 4 space separation to tabs or 2 spaces, etc. Such changes can often make identification of actual content changes difficult for translators.

If possible, configure your editor’s formatting settings such that they follow the guidelines outlined in this document. If you cannot do so, please disable autoformatting, or find a different tool that allows such configurability.

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.

Edit this document

Edit this document

The source code of this file is hosted on GitHub. Everyone can update and fix errors in this document with few clicks - no downloads needed.

  1. Login with your GitHub account.
  2. Go to Zend Framework Documentation Standard on GitHub.
  3. Edit file contents using GitHub's text editor in your web browser
  4. Fill in the Commit message text box at the end of the page telling why you did the changes. Press Propose file change button next to it when done.
  5. On Send a pull request page you don't need to fill in text anymore. Just press Send pull request button.
  6. Your changes are now queued for review under project's Pull requests tab on GitHub.