The current Zend Framework documentation suffers from a number of issues, most prominently:
* No good tutorial. The "learning" section is unstructured, and the quick start does not cover a cohesive example. Additionally, no examples are carried throughout the documentation.
* *Missing information.*
** Much of the documentation does not cover all configuration options or available functionality, including available methods.
** Most components do not include complete examples.
** Extension points are often not discussed in complete detail. (Example given: most interfaces available are not detailed in the documentation.)
* *Unpredictable format.*
** Each component documents things in a slightly different way, making discovery of features difficult.
** Some components will list options in one format, others in an entirely different way. This makes finding and understanding the options difficult.
* 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.
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.
h2. End-user or tutorial documentation
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.
The documentation will begin with a quick start guide to developing with ZF2, demonstrate installing modules, and then module creation.
h2. Structure
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:
* 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.
h3. Theory of Operation
First, all components will include sections on the following:
* *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.
h4. Identifiers
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).
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.
{code:xml}
<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<section id="zend.loader.class-map-autoloader">
<info><title>The ClassMapAutoloader</title></info>
<section id="zend.loader.class-map-autoloader.intro">
<info><title>Overview</title></info>
</section>
<section id="zend.loader.class-map-autoloader.quick-start">
<info><title>Quick Start</title></info>
</section>
<section id="zend.loader.class-map-autoloader.options">
<info><title>Configuration Options</title></info>
<variablelist>
<title>ClassMapAutoloader Options</title>
<varlistentry>
<term></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="zend.loader.class-map-autoloader.methods">
<info><title>Available Methods</title></info>
<variablelist>
<varlistentry id="zend.loader.class-map-autoloader.methods.method-name">
<term>
<methodsynopsis>
<methodname></methodname>
<methodparam>
<funcparams></funcparams>
</methodparam>
</methodsynopsis>
</term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="zend.loader.class-map-autoloader.examples">
<info><title>Examples</title></info>
<example id="zend.loader.class-map-autoloader.examples.example-name">
<info><title></title></info>
<para></para>
<programlisting language="php"><![CDATA[
]]></programlisting>
</example>
</section>
</section>
{code}
We will likely develop a tool to autogenerate the "Methods" section from the class files; this will speed up writing these sections, and provide a nice skeleton from which to work.
h3. Examples
* [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]
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.
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.
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.
[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.
h3. Migration
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/] is one such tool; [Zeta Components' Document component|http://zetacomponents.org/documentation/trunk/Document/tutorial.html#writing-rst] 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.
...