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

Changes (74)

View Page History
{toc:maxLevel=3}
<ac:macro ac:name="toc"><ac:parameter ac:name="maxLevel">3</ac:parameter></ac:macro>

<p>Authors: Rob Allen, Gary Hockin, Matthew Weier O'Phinney, Enrico Zimuel</p>

h2. Overview
<h2>Overview</h2>

<p>The current Zend Framework documentation suffers from a number of issues, most prominently:</p>

<ul>
* No <li>No good tutorial. The "learning" &quot;learning&quot; section is unstructured, and the quick start does not cover a cohesive example. Additionally, no examples are carried throughout the documentation.</li>
* *Missing information.*
<li><strong>Missing information.</strong>
<ul>
** Much <li>Much of the documentation does not cover all configuration options or available functionality, including available methods.</li>
** Most components do not include complete examples.
<li>Most components do not include complete examples.</li>
** Extension <li>Extension points are often not discussed in complete detail. (Example given: most interfaces available are not detailed in the documentation.)</li>
* *Unpredictable format.*
</ul>
</li>
<li><strong>Unpredictable format.</strong>
<ul>
** Each <li>Each component documents things in a slightly different way, making discovery of features difficult.</li>
** Some <li>Some components will list options in one format, others in an entirely different way. This makes finding and understanding the options difficult.</li>
</ul>
</li>
* Documentation <li>Documentation is difficult to create, as it requires learning DocBook, and having a working DocBook toolchain available to lint and render documentation. Currently, this means either having a unix-like environment or Cygwin.</li>
</ul>

After some brainstorming and discussion, we feel:

* The manual should consist of two distinct entities: an end-user or tutorial, and the reference manual.
* Documentation in the reference manual should follow a standard structure for each entity documented.
* We should move to a format that's more concise and easier to learn, specifically reStructuredText and Sphinx.
<p>After some brainstorming and discussion, we feel:</p>

h2. End-user or tutorial documentation
<ul>
<li>The manual should consist of two distinct entities: an end-user or tutorial, and the reference manual.</li>
<li>Documentation in the reference manual should follow a standard structure for each entity documented.</li>
<li>We should move to a format that's more concise and easier to learn, specifically reStructuredText and Sphinx.</li>
</ul>

This documentation should be primarily a narrative, following along in the development of a working example application. The example application should be sufficiently non-trivial to allow discussion of a wide swath of ZF2 features, including the MVC and related components, DB, Authentication and ACL, and features such as navigation and pagination.

At this time, we are planning on re-purposing the "Album" application from [Rob Allen's ZF2 tutorial|http://akrabat.com/zend-framework-2-tutorial/], as it demonstrates many of these features already.
<h2>End-user or tutorial documentation</h2>

The documentation will begin with a quick start guide to developing with ZF2, demonstrate installing modules, and then module creation.
<p>This documentation should be primarily a narrative, following along in the development of a working example application. The example application should be sufficiently non-trivial to allow discussion of a wide swath of ZF2 features, including the MVC and related components, DB, Authentication and ACL, and features such as navigation and pagination.</p>

h2. Structure
<p>At this time, we are planning on re-purposing the &quot;Album&quot; application from <a href="http://akrabat.com/zend-framework-2-tutorial/">Rob Allen's ZF2 tutorial</a>, as it demonstrates many of these features already.</p>

Many ZF users have indicated that we should take an additional idea from the PHP manual, and use a standard layout for every component and/or class. This will provide several benefits:
<p>The documentation will begin with a quick start guide to developing with ZF2, demonstrate installing modules, and then module creation.</p>

* Component authors know exactly what documentation they must provide, and how to do so.
* Users know exactly where to look for specific functionality of a component and/or class.
* Such an approach lends itself well to consistency of URLs as well, further increasing predictablity.
<h2>Structure</h2>

h3. Theory of Operation
<p>Many ZF users have indicated that we should take an additional idea from the PHP manual, and use a standard layout for every component and/or class. This will provide several benefits:</p>

First, all components will include sections on the following:
<ul>
<li>Component authors know exactly what documentation they must provide, and how to do so.</li>
<li>Users know exactly where to look for specific functionality of a component and/or class.</li>
<li>Such an approach lends itself well to consistency of URLs as well, further increasing predictablity.</li>
</ul>

* *Overview*, which will detail the problem the component addresses, as well as theory of operation.
* *Quick Start*, which will provide an overview and examples detailing the most common use case(s).
* *Configuration Options*, which will provide an overview of each configuration option available (if any), including accepted values.
* *Available Methods*, which will detail each available method, the arguments it accepts, and the return value.
* *Examples*, which will be a "cookbook" like chapter, showing additional use cases. This section will likely expand for each component over time to cover frequently asked questions.

This proposal does not currently seek to address components with adapters, plugins, helpers, etc.; a later proposal will address structure for such components.
<h3>Theory of Operation</h3>

h4. Identifiers
<p>First, all components will include sections on the following:</p>

Identifiers will be named after the namespace and component; "CamelCased" names will be converted to "lowercase-dash-separated". Files will be named after the top-level identifier in the document; e.g., "Zend\Loader\ClassMapAutoloader" would be represented with the identifier "zend.loader.class-map-autolaoder", in the file "zend.loader.class-map-autoloader.<ext>" (<ext> will likely be "rst" if we use reStructuredText, per this RFC).
<ul>
<li><strong>Overview</strong>, which will detail the problem the component addresses, as well as theory of operation.</li>
<li><strong>Quick Start</strong>, which will provide an overview and examples detailing the most common use case(s).</li>
<li><strong>Configuration Options</strong>, which will provide an overview of each configuration option available (if any), including accepted values.</li>
<li><strong>Available Methods</strong>, which will detail each available method, the arguments it accepts, and the return value.</li>
<li><strong>Examples</strong>, which will be a &quot;cookbook&quot; like chapter, showing additional use cases. This section will likely expand for each component over time to cover frequently asked questions.</li>
</ul>

h4. XML Structure

While we likely will not use DocBook as the final structure, it is a good format for illustrating the proposed document structure.
<p>This proposal does not currently seek to address components with adapters, plugins, helpers, etc.; a later proposal will address structure for such components. </p>

{code:xml} <h4>Identifiers</h4>

<p>Identifiers will be named after the namespace and component; &quot;CamelCased&quot; names will be converted to &quot;lowercase-dash-separated&quot;. Files will be named after the top-level identifier in the document; e.g., &quot;Zend\Loader\ClassMapAutoloader&quot; would be represented with the identifier &quot;zend.loader.class-map-autolaoder&quot;, in the file &quot;zend.loader.class-map-autoloader.&lt;ext&gt;&quot; (&lt;ext&gt; will likely be &quot;rst&quot; if we use reStructuredText, per this RFC).</p>

<h4>XML Structure</h4>

<p>While we likely will not use DocBook as the final structure, it is a good format for illustrating the proposed document structure.</p>

<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->

<programlisting language="php"><![CDATA[
]]]]><![CDATA[></programlisting>
</example>
</section>
</section>
{code}
]]></ac:plain-text-body></ac:macro>

<p>We will likely develop a tool to autogenerate the "Methods" &quot;Methods&quot; section from the class files; this will speed up writing these sections, and provide a nice skeleton from which to work.</p>

h3. Examples
<h3>Examples</h3>

* [ClassMapAutoloader example|http://git.zendframework.com/?a=viewblob&p=zf&h=901fa6242cd52082092a7285bd8b10c910454ee8&hb=df37795d665bcf10d3445327643f0c37e8e585a6&f=documentation/manual/en/module_specs/Zend_Loader-ClassMapAutoloader.xml]
* [SplAutloader example|http://git.zendframework.com/?a=viewblob&p=zf&h=b59067eaad47fc836563fc063f402562b456412c&hb=df37795d665bcf10d3445327643f0c37e8e585a6&f=documentation/manual/en/module_specs/Zend_Loader-SplAutoloader.xml]
* [StandardAutoloader example|http://git.zendframework.com/?a=viewblob&p=zf&h=bf989f707453079187170fe3cd96ceb513a034ee&hb=df37795d665bcf10d3445327643f0c37e8e585a6&f=documentation/manual/en/module_specs/Zend_Loader-StandardAutoloader.xml]
* [AutoloaderFactory example|http://git.zendframework.com/?a=viewblob&p=zf&h=c6cf2a699b4de521b86bddb71b33679a24f44084&hb=df37795d665bcf10d3445327643f0c37e8e585a6&f=documentation/manual/en/module_specs/Zend_Loader-AutoloaderFactory.xml]
* [classmap_generator.php example|http://git.zendframework.com/?a=viewblob&p=zf&h=4d3ad731c917f6d49647e22b69e5d0805798b080&hb=df37795d665bcf10d3445327643f0c37e8e585a6&f=documentation/manual/en/module_specs/Zend_Loader-Classmap_Generator.xml]
<ul>
<li><a href="http://git.zendframework.com/?a=viewblob&amp;p=zf&amp;h=901fa6242cd52082092a7285bd8b10c910454ee8&amp;hb=df37795d665bcf10d3445327643f0c37e8e585a6&amp;f=documentation/manual/en/module_specs/Zend_Loader-ClassMapAutoloader.xml">ClassMapAutoloader example</a></li>
<li><a href="http://git.zendframework.com/?a=viewblob&amp;p=zf&amp;h=b59067eaad47fc836563fc063f402562b456412c&amp;hb=df37795d665bcf10d3445327643f0c37e8e585a6&amp;f=documentation/manual/en/module_specs/Zend_Loader-SplAutoloader.xml">SplAutloader example</a></li>
<li><a href="http://git.zendframework.com/?a=viewblob&amp;p=zf&amp;h=bf989f707453079187170fe3cd96ceb513a034ee&amp;hb=df37795d665bcf10d3445327643f0c37e8e585a6&amp;f=documentation/manual/en/module_specs/Zend_Loader-StandardAutoloader.xml">StandardAutoloader example</a></li>
<li><a href="http://git.zendframework.com/?a=viewblob&amp;p=zf&amp;h=c6cf2a699b4de521b86bddb71b33679a24f44084&amp;hb=df37795d665bcf10d3445327643f0c37e8e585a6&amp;f=documentation/manual/en/module_specs/Zend_Loader-AutoloaderFactory.xml">AutoloaderFactory example</a></li>
<li><a href="http://git.zendframework.com/?a=viewblob&amp;p=zf&amp;h=4d3ad731c917f6d49647e22b69e5d0805798b080&amp;hb=df37795d665bcf10d3445327643f0c37e8e585a6&amp;f=documentation/manual/en/module_specs/Zend_Loader-Classmap_Generator.xml">classmap_generator.php example</a></li>
</ul>

h2. Use reStructuredText and Sphinx

[reStructuredText and Sphinx|http://sphinx.pocoo.org/] are tools for developing project documentation. reStructuredText is a simple markup language similar to Markdown. Unlike markdown, however, it supports defining labels and cross-referencing -- in otherwords, inter-document linking. Additionally, it supports features we use in DocBook currently, such as notes and warnings, and language-specific syntax highlighting of code examples.
<h2>Use reStructuredText and Sphinx</h2>

One concern for the ZF documentation has always been supporting multiple output formats. Sphinx allows generating HTML, LaTeX (and thus PDF), Windows HTML help files, manual pages, and even simply plain text.
<p><a href="http://sphinx.pocoo.org/">reStructuredText and Sphinx</a> are tools for developing project documentation. reStructuredText is a simple markup language similar to Markdown. Unlike markdown, however, it supports defining labels and cross-referencing &ndash; in otherwords, inter-document linking. Additionally, it supports features we use in DocBook currently, such as notes and warnings, and language-specific syntax highlighting of code examples. </p>

One final concern is search. Right now, the ZF team manually creates Lucene indices for each new release, and has code for searching those indices in the website. reST+Sphinx do not offer this out of the box. This gives us two options. First, we can do similarly to what we do now, which is index the generated markup. Alternately, we can use a service such as [Read the Docs|http://readthedocs.org], which will auto-compile our documentation from our repository using Sphinx, and provide search for the generated documentation.
<p>One concern for the ZF documentation has always been supporting multiple output formats. Sphinx allows generating HTML, LaTeX (and thus PDF), Windows HTML help files, manual pages, and even simply plain text.</p>

[Read the Docs|http://readthedocs.org] would fill several roles: search capabilities, version-specific documentation, and syntax checking/preview. We feel these benefits alone make a switch in formats quite compelling.
<p>One final concern is search. Right now, the ZF team manually creates Lucene indices for each new release, and has code for searching those indices in the website. reST+Sphinx do not offer this out of the box. This gives us two options. First, we can do similarly to what we do now, which is index the generated markup. Alternately, we can use a service such as <a href="http://readthedocs.org">Read the Docs</a>, which will auto-compile our documentation from our repository using Sphinx, and provide search for the generated documentation.</p>

h3. Migration
<p><a href="http://readthedocs.org">Read the Docs</a> would fill several roles: search capabilities, version-specific documentation, and syntax checking/preview. We feel these benefits alone make a switch in formats quite compelling.</p>

<h3>Migration</h3>

<p>Of course, migration is an issue should we choose this approach. Fortunately, there are tools to help automate the process. [pandoc|http://johnmacfarlane.net/pandoc/] <a href="http://johnmacfarlane.net/pandoc/">pandoc</a> is one such tool; [Zeta <a href="http://zetacomponents.org/documentation/trunk/Document/tutorial.html#writing-rst">Zeta Components' Document component|http://zetacomponents.org/documentation/trunk/Document/tutorial.html#writing-rst] component</a> is another. We will likely need to experiment with both tools to find the one that best suits our needs, and document issues we run across so as to better understand what manual processes will be needed to complete migration.</p>