Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="toc"><ac:parameter ac:name="maxLevel">3</ac:parameter></ac:macro>

<h2>Overview</h2>

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

<ul>
<li><strong>Missing information.</strong>
<ul>
<li>Much of the documentation does not cover all configuration options or available functionality, including available methods.</li>
<li>Most components do not include complete examples.</li>
<li>Extension points are often not discussed in complete detail. (Example given: most interfaces available are not detailed in the documentation.)</li>
</ul>
</li>
<li><strong>Unpredictable format.</strong>
<ul>
<li>Each component documents things in a slightly different way, making discovery of features difficult.</li>
<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>
</ul>

<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>

<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>

<h2>Use DocBook5</h2>

<p>Zend Framework 2 will mark the first version of the framework where documentation is written using DocBook5. This will help simplify structure and syntax, and also work better with next generation tools such as PhD, REST-NG, etc.</p>

<h2>Theory of Operation</h2>

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

<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 "cookbook" like chapter, showing additional use cases. This section will likely expand for each component over time to cover frequently asked questions.</li>
</ul>

<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>

<h3>Identifiers</h3>

<p>Identifiers will be named after the namespace and component; "CamelCased" names will be converted to "lowercase-dash-separated".</p>

<h3>XML Structure</h3>

<p>The basic structure of a document will look as follows:</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 -->
<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[
]]]]><![CDATA[></programlisting>
</example>
</section>
</section>
]]></ac:plain-text-body></ac:macro>

<p>Important items to note include:</p>

<ul>
<li>Configuration options will use a <variablelist> element with a <varlistentry> element per configuration option.</li>
<li>Methods will be detailed using a <varlistentry> per method. Parameters will be described using a <funcparams> element, containing simply a string with the elements:
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<funcparams>Foo $foo, array $options = null</funcparams>
]]></ac:plain-text-body></ac:macro>
The arguments will be detailed within the <listitem> if they need explanation.</li>
</ul>

<p>We will also 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.</p>

<h2>Examples</h2>

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

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Sep 24, 2010

    <p>Like the structure,think this will make things much more consistent. <br />
    During the milestone will the formatting be fixed on the website?</p>

  2. Sep 24, 2010

    <p>the structure looks good for me too, except "quick start" and "examples", they seems the same thing</p>

    <p>doc writer will have to write examples in two places</p>

    <p>imo the xml structure could have just one node for examples and use cases, then the processor could extract/move/copy from this "examples" section one or more nodes to quickstart to generate html</p>

  3. Sep 24, 2010

    <p>Does it have to be an XML?</p>

    <p>I'm asking this as <a href="http://www.varnish-cache.org/docs/trunk/phk/sphinx.html">this article</a> raises a valid point.</p>

    1. Sep 25, 2010

      <p>ZF Documentation is build upon docbook. See <a class="external-link" href="http://docbook.org">http://docbook.org</a><br />
      This allows us to have the documentation validated (see our docu-checker), and converted in any format (html, pdf, chm...)</p>

    2. Oct 30, 2010

      <p>Well, I think it does raise a valid point. DocBook isn't a bad format, but it isn't really readable when it isn't rendered.</p>

      <p>DocBook kinda is a defacto standard for a lot of documentation purposes, but I think this is a good time to explore other possibilities as well, and Sphinx + reStructuredText sounds like a good alternative.</p>

      1. Oct 30, 2010

        <p>I tend to agree. Maybe something that doesn't need to be "compiled" externally. I'm fine with whatever standard format like docbook underneath. Really big pain in the butt during development to compile documentation. Would be better if we had something like a Zend_Documentation that used Zend_Cache_Frontend_File on the source files to automatically re-render; this would give the benefit of better portability (phD on windows is a nightmare), quicker development, also allowing for grabbing of specific parts of documentation from other parts of your application. This would make it easy for consumers of ZF to write their own documentation as well instead of going on their own how should i use docbook escapade.</p>

  4. Sep 25, 2010

    <ul>
    <li>The comment section should be equal to existing manual. Otherwise we will have problems with our validation tool when there is no defined way anymore.</li>
    </ul>

    <ul>
    <li>The example section alone is not enough. Many components have additional informations which are themself covered within 2-3 chapters. We should not limit the documentation to these chapters mentioned above but have these chapters as minimum requirement. It should be allowed to have additional chapters integrated.</li>
    </ul>

    <ul>
    <li>What should be done with the existing documentation tool? Actually it is written and hosted by community (Mickael). Translation and checking documentation becomes much easier with it. It would be no good idea to throw it away in my opinion.</li>
    </ul>

  5. Sep 25, 2010

    <p>In past we often had issues with not updated examples (Not working anymore)</p>

    <p>Is there a chance to to store examples within a *.php file and to include this in docbook?<br />
    Than we could create UnitTests for examples.</p>

    1. Sep 27, 2010

      <p>This is just the first proposal, and I'm looking primarily at structure. What you suggest makes sense – though it would actually be hard to do tests on many of the examples as they are incomplete (no autoloading setup, potentially not showing imports, etc.).</p>

  6. Sep 27, 2010

    <p>Shoulda been more specific with the proposal title <ac:emoticon ac:name="wink" />. Probably off topic (am still thinking about the content structure which is what the proposal mostly addresses) but my main problem with the documentation writing is that it's painful. The sect1,sect2 levels can't be rendered in an XML editor and resorting to plain text editing doesn't cut it for me personally - there are Docbook friendly editors out there that are far easier, faster and simple. If we are going to start restructuring documentation at a basic level, we could start with the format and make it more WYSIWYG Docbook editor friendly. Also, Docbook 5. Pretty please with sugar on top? Honey? Glucose syrup? </p>

    1. Sep 27, 2010

      <p>Yes – DocBook 5 is a must (we actually have to do some conversions currently in order for PhD to render docs, as it uses 5 as the base supported version).</p>

      <p>As for the WYSIWYG editor situation – we have two issues:</p>
      <ol>
      <li>Versioning. Most WYSIWYG editors I've seen tend to put all content for a given block on the same line, making it very, very hard to determine what exactly has changed from one version to the next.</li>
      <li>I have absolutely no idea what you mean by "sect1/sect2 levels can't be rendered". Can you provide me more detail on this? (Not necessarily in the comments here; email would be fine.)</li>
      </ol>

      <p>The format I've suggested is very good semantically. If there are better tags that would make compliance with formal DocBook editors easier, I'm up for it – but, again, I'd need to know what those are.</p>

      1. Sep 28, 2010

        <p>I used in the past XMLMind. After some settings it's possible to maintain versioning (indentation tabs, maximum line length, cdata in programlisting). With our checker we are able to detect change in the structure and in the text (independently of the formatting of the source).</p>

  7. Oct 11, 2010

    <p>I discovered that neither the xsltproc setup we have in trunk nor PhD were capable of rendering <refentry> items, so I've altered the structure to use <variablelist> for methods, which each method acting as a <varentry>. This also removes some of the duplication present in the original <refentry> setup.</p>

  8. Feb 04, 2011

    <p>Excellent proposal. As you note consistency is key, with common sections and clear explanations of all methods in a common format. I think the current docs are great and though complex at times I've always been impressed with the breadth of docs pages in the project. This is a great opportunity to improve things for 2.0</p>

    <p>Other things I think are important:</p>

    <ul>
    <li>Focus on the simple way to do things first, then delve into the complex. Various areas of the ZF docs do jump into complex features before fully explaining the simple use case.</li>
    <li>Detail best practise and gotchas early on in the docs. Bear in mind many beginners tend to read a component page-by-page rather than skip around.</li>
    <li>More example code for common use cases (for example, how to set a single custom error message for validation on a form element. A pretty common use case, but one that requires jumping back and forth between Zend_Form and Zend_Validate in the docs for beginners)</li>
    <li>Interlink different sections where functionality is shared / can be done in different ways. (i.e. link Zend_App autoloader via Zend_loader, Zend Validate via Zend Form, etc). One suggestion would be to introduce a "Related links/components" area on the page.</li>
    <li>Split long pages up (aka Zend_View_Helpers)</li>
    <li>Improved search, ideally returning classes/methods first, then matches in text.</li>
    </ul>

    <p>For the example docs written in this proposal are there HTML versions that can be viewed? </p>

    <p>Is the idea to test this new structure on one component first, if so has this happened yet? (sorry, not sure whether the 2.0 code is far enough for this to be feasible)</p>

  9. Apr 02, 2011

    <p>I think special links to wiki in documentation source can be useful. Per component or even per section.</p>

    <p>Based on such links wiki categories can be autocreated and linked back to docs, similar to svn and JIRA linking. <br />
    One moderated place for non-cla end users. Comments, component extended use cases and other stuff now scattered throughout internet.</p>

    <p>Not sure if it possible, just an idea</p>

  10. May 20, 2011

    <p>I don't have much to add to technical details of how docs are written, or how they work. I hope this is still the correct page to add my thoughts though.</p>

    <p>One thing I've noticed on various components, it would be nice to have some sort of feedback for them in place.</p>

    <p>And by feedback, I don't necessarily mean comments (though of course they should be kept), but maybe a rating for people: <em>How do you rate the quality of this page?</em>. Google or other people use something like, <em>Did you find this helpful?</em>. </p>

    <p>I think that's badly needed, as these things would serve as indicator where things go really wrong.</p>

    <p>Generally, I think a rule needs to be imposed on documentation: more examples, less theory of operation. For theory of operation you can always link off-site to Wikipedia or some other resource, or maybe add a page in the end, but currently examples are badly, badly needed.</p>

    <p>I'm not sure of the Atlassian suite allows you to generate a report on how much of the code is actually covered/menitoned by the documentation. That would be a great indicator on where to start. </p>

    <p>Maybe that would also allow more contributions from people who don't write a lot of code.</p>