Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Reorganization of documentation Component Proposal

Proposed Component Name Reorganization of documentation
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Reorganization of documentation
Proposers Mickael Perraud
Thomas Weidner
Zend Liaison TBD
Revision 0.1 - 7 January 2009: Initial Draft.
0.2 - 17 January 2009: Add Zend_Tool provider
0.3 - 17 March 2009: of the conversation between Thomas Weidner, Wil Sinclair, Matthew Weier O'Phinney and Mickael Perraud on IRC
0.4 - 22 March 2009: add informations about a new translator tool
0.5 - 25 April 2009: Added documentation standard (wiki revision: 33)

Table of Contents

1. Overview

One main goal => simplification:

  • simplification of management
  • simplification of translation
  • simplification of rendering

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

...

4. Dependencies on Other Framework Components

5. Theory of Operation

Simplification without any BC

This part is fully compatible with actual system without any BC. Goals are:

  • centralized for all languages: figures, compilation process
  • simplification of the translation and especially of the update
  • enhance html rendering with syntax highlighting
  • "create" pdf rendering with syntax highlighting

Centralized figures and compilation process:

  • creation of a directory: "/trunk/documentation/build"
  • creation of a directory: "/trunk/documentation/build/figures" for all figures, this could be modify by using "/trunk/documentation/manual/en/figures" for committing access if you need, Zend_Tool provider can verify if the images exist in language subdirectory and can take them.
  • rewrite actual Makefile as Zend_Tool provider
  • adding some PHP process
  • creation html.xsl.in and pdf.xsl.in (based on actual ones)

Enhance CHM rendering:

Creation of pdf rendering:

  • creation of the associated stylesheet to not fork docbook-xsl
  • using of same images as CHM rendering

Maintain actual system with Zend_Tool provider:

  • "zf clean manual"
  • "zf check manual" => English doc
  • "zf check manual fr" => French doc
  • "zf build manual" => create HTML English doc
  • "zf build manual html fr" => create HTML French doc
  • "zf build manual chm" => create CHM English doc (need Html Help Workshoop, could be set ENVIRONMENT variable)
  • "zf build manual chm fr" => create CHM French doc
  • "zf build manual pdf-fop" => create PDF English doc with fop
  • "zf build manual pdf-fop fr" => create PDF French doc with fop

Needed (in addition to http://framework.zend.com/wiki/display/ZFDEV/Translator+-+Manual+Compilation+Instructions):

  • FOP 0.95.0
  • PHP

Facilitate translations

Having the same manual.xml.in for all languages

This could be realized by using xml entities. See http://framework.zend.com/svn/framework/standard/branches/user/mikaelkael/manual/manual.xml.in and http://framework.zend.com/svn/framework/standard/branches/user/mikaelkael/manual/en/language-defs.ent . We have to create language-defs.ent for each language. The manual.xml.in contains the fall back to English documentation.

Cut files by sect2 instead of sect1

Some actual files are very long to translate (Zend_Db_Adapter), divisions will facilitate the translation and especially the update. In the same idea, as mentioned in the comments of this page, it would be good to limit the size (in number of words for example) of a generated page (in HTML or CHM format).

Put all 'xinclude' in manual.xml.in

To be sure that all languages will contain all files, we have to limit the using of 'xinclude' in /module_specs/* or /ref/* files. This could be easier if we apply the precedent paragraph (cutting).

Creating different snippets

My main example is 'requirements.xml'. We have to create snippets for table titles and headers, and for the word 'Hard' and 'Soft'. With this, the file 'requirements.xml' don't need to be translate (or update) each time.

Rewrite building process as Zend_Tool provider

See below

Sharing examples

Example updates are the most important documentation updates. The main reason we don't share them at this point is translation of the comments.
The first step is to link examples, this must be done by adding an id to all programlisting tags. After there is two possibilities, translations of the comments or not.
In English, we'll have for example:

In translated files, we'll just have:

or with translations of the comments:

This syntax allow to test English examples (parse error for examples). At time of rendering, we can remove '#\d+#' tags. If we add a comment in English example and it isn't translated then we fallback to English comments. The order of the comments is not important so we could add or remove them in English file if necessary. If we have phpDoc in the example without '#\d#' tag, we don't search for translations.

Documentation standard

To improve the look and feel of the manual, and to get all chapters and pages rendered in the same style even if multiple people are involved a documentation standard has to be applied.

The following rules should be forced to all translation files:

Line length

Maximum line length of 100 chars including tags and attributes and intendation.
There is only one exception to this rule. Attributes themself are allowed to exceed the 100 chars as they are not allowed to be seperated.

Intendation

Tags which are at the same level must have the same intendation

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

It is not allowed to have multiple tags within one line

Programmlisting

Beginning programmlisting must apply role of php, cdata and starting intendation

Programmlistings must not add linebreaks or whitespaces at the beginning or the end, as they would then be rendered.

Ending CDATA Tag and programmlisting at the same line

Seperation between tags

Tags at the same level must be seperated by a empty line to improve readability

Classes

The tag classname must be used for all Zend Framework classes. The code tag is not allowed. This rule has only to be applied if the classname stands alone. Other content is not allowed within this tag.

Variables

Variables must be wrapped in the varname tag. Variables must be written with $ otherwise they are not recognised as variables. Other content is not allowed within this tag.

Methods

Methods must be wrapped in the methodname tag. Methods must be written with () otherwise they are not recognised as methods. Other content is not allowed within this tag.

Constants

Constants must be wrapped in the constant tag. Constants must be written UPPERCASE otherwise they are not recognised as constants. Other content is not allowed within this tag.

Filenames and Paths

Filenames and paths must be wrapped in the filename tag. They must include eighter a "." or "/" char. Other content is not allowed within this tag.

Commands

Commands and programm calls must be wrapped in the command tag. Commands must include a whitespace otherwise they are not recognised as variables. Other content is not allowed within this tag.

Code

The usage of the code tag is not allowed in favor of seperation to filename, varname and constant.

Title tag

The title is not allowed to hold any tags

Ending spaces

Ending spaces are not allowed

Multiple new lines

Multiple new lines are not allowed

Empty tags

Empty tags (para, example and others) are not allowed. They must contain text or underlaying tags.

No tabs

The usage of TABS is not allowed. Instead intendation of 4 spaces must be used.

Line endings

Only Unix lineendings are allowed. Other line endings like Windows or Mac are must not be used.

XML Tags

Each manual file has to include the following xml declarations at file start

XML Files from translated languages must also include a revision tag which must notify the revision of the english file this translation is based of.

Short tags

Short tags must not be used. Wether in description nor in code.

Note that there already exists a tool which checks parts of this standard. You can find it under: http://mikaelkael.dyndns.org/checker

To go further

Extras documentation

After etablishing rules (with this proposal) on standard manual, we just have to apply same rules in extras documentation.

Quickstart translation

Actual quickstart (http://framework.zend.com/docs/quickstart) could be translate in Docbook format and put in http://framework.zend.com/svn/framework/standard/trunk/documentation/manual/en/quickstart or in http://framework.zend.com/svn/framework/standard/trunk/documentation/quickstart/en

Enhance HTML rendering

For the moment, table of contents ar only rendered for level 1 section (http://framework.zend.com/manual/en/zend.acl.html has a toc but not http://framework.zend.com/manual/en/zend.acl.refining.html). We could add TOC for all rendered file by using http://docbook.sourceforge.net/release/xsl/current/doc/html/generate.section.toc.level.html

Adding index

This part is a big one. An automatic index could be rendered by adding index tag inside all the actual docuementation. For example, to add an index 'Zend_Acl' in Zend_Acl-Advanced.xml, we have to replace:

by:

The job of determination of the words (or sentences) to index must be do in English and can change in translated files.

Modify MANUAL TRANSLATION STATUS (http://framework.zend.com/manual/status)

This page doesn't really show if a translation is outdated or not. If I take SVN 13906 to SVN 13930, these commits are just to modify tabs to spaces. Actual manual status is not able to see difference between real changes or 'esthetic' changes. Since a long time, some translators (French, Japanese or Deutsch) use a revision tag at the top of their translations to differentiate real and 'esthetic' changes:

Here is a link to test a new translator tool: http://mikaelkael.dyndns.org/checkzf. This tool can:

  • check if you use the revision tag and takes it in this case, otherwise it takes the last revision change (like today in http://framework.zend.com/manual/status)
  • show you the out-of-date and the non translated files, instead of showing you all the files.
  • can retrieve for an out-of-date file the difference of the English file between the last translated revision and the last revision of English file, so if they are multiples revisions of the English file, they are all compile (it take into account reorganization of the SVN in revision 9506).
  • can show you the last building check and associated output.
  • can show you difference of number of tags between English and translated file. This is available for multiple tags: 'sectX', 'para', example'...

Set up a documentation review

Because many of us are no native English, it would be great to add a documentation review. This could be simply do by adding a special tag at the top of the file:

When a new part is added, the tag is setting to no. You will find below a script that can render reviewed page based on this tag. This could be used of course for English files but also for translated ones.

Testing examples of the documentation

At least, we should test for parse error. Then we could link examples between them with special comments which would be cleared at the time of rendering. For example with Zend_Db, the first with id 'zend.db.adapter.connecting.constructor.example' that describe the connection could be call by the second one:

Unify Migration chapters

Actually we have a migration chapter for each component. This makes it very difficult when you want to migrate to a new release as the user must search every single component if there are migration notes.

To make things easier we should add a single migration chapter where all migration notes from all components are collected. So the user has one place where all migration notes are displayed. Within the component chapter a link can be places to the migration chapter. This makes live much easier for all people who want to update to a new release.

6. Milestones / Tasks

...

7. Class Index

...

8. Use Cases

UC-01

... (see good use cases book)

9. Class Skeletons

]]></ac:plain-text-body></ac:macro>

]]></ac:plain-text-body></ac:macro>

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jan 07, 2009

    <p>sounds great, may this be a good place to ask for integration of the API docs with the documentation? Rendered as the same layout? It shouldn't be a problem to generate a docbook output from phpDocumentor or?</p>

    <p>Are backreferences possible between manual and occourences of Class names for example?</p>

    <p>ezComponents has a nice mix in this case.</p>

    1. Jan 08, 2009

      <p>This is version 0.1, it's more a copy/paste of different mail than a real proposal. I want to cover: standard and extras manual, quickstart tutorial (<a href="http://framework.zend.com/docs/quickstart">http://framework.zend.com/docs/quickstart</a>), rendering of the doc. I noted your mail concerning testing examples (i also have ideas for this <ac:emoticon ac:name="wink" /> ).<br />
      I will arrange this proposal this evening. I will also be on IRC to speak about it.</p>

  2. Jan 08, 2009

    <p>Looks good <ac:emoticon ac:name="wink" /></p>

    <p>As addition: Add indezes. CHM and PDF support them and will create a reference page when rendering.<br />
    HTML normally ignores these. Docbook has support for index words.</p>

    <p>This way someone could search for "APC" and get all occurances of APC within CHM and PDF file within the manual.</p>

    <p>Note that both also accept a TOC (table of content) which is also supported by Docbook. This would also be a very good addition.</p>

  3. Mar 17, 2009

    <p>@Mickael:<br />
    Thank you for the addition. I think that we have now all points written which we talked about.<br />
    I've moved the proposal itself now for public review but I don't think that we have missed anything big.</p>

    <p>Just as note for Zend-Internal Dev Team:<br />
    We can only propose to simplify the whole process where community is involved. Still, someone must create the manual when a new release is build and have to add the outcomming files to the homepage for public download.</p>

    <p>Maybe Zend itself should also think of ways, how this process can be simplified on their side, to reduce the work done for each release from Zend. And to reduce the point of failure (see the often broken status page for example, or the manual which is often online several days after the release)</p>

  4. Mar 17, 2009

    <p>@Mickael:<br />
    One thing which should also be written and proposed, even if it's nothing which could be done by us is:</p>

    <p>To be able to add/write comments at the online manual itself.<br />
    They should not be deleted when a new translation or changes are made.</p>

    <p>Maybe it should also be possible to move them between pages so that when pages are deleted/renamed/splitted the comments can still be held available and moved to the new page.</p>

    <p>Best example is the online PHP manual.</p>

    <p>A second note:<br />
    The pages at the php online manual are not big... we should also aim to have a maximum limit of words/rows per page. It must fit maximum one printer page, for convinience it should even be smaller.</p>

    <p>We should also aim to have more code snippets within the manual. But this one only a suggestion.</p>

    1. Mar 21, 2009

      <p>@Thomas: I integrated your comments. Concerning manual comments, I add the link to the related issue: <a href="http://framework.zend.com/issues/browse/ZF-4968">ZF-4968</a>: Add php.net style comments to <a class="external-link" href="http://framework.zend.com/manual/en/">http://framework.zend.com/manual/en/</a></p>

  5. Mar 24, 2009

    <p>Can we have a button to transfer a comment into an issue?</p>

    <p>I know Jira has all kinds of APIs so that should be possible. The advantage of this would be the following:</p>

    <p>1) Say I come across a manual entry that is outdated or whatever, I can leave a comment.<br />
    2) Whoever from the development team sees it, they hit the button and it creates an issue in Jira for it which can be assigned to someone by default (or the PM) and then it gets fixed/done.</p>

    <p>We are using the same "workflow" on PEAR and it's been pretty successful catching doc bugs.</p>

    1. Mar 24, 2009

      <p>In my understanding this is nothing which could be handled by this proposal.</p>

      <p>The community has wether access to the homepage nor to jira. Both are handled and driven by Zend themself. So there is no way for us to integrate this.</p>

  6. Apr 02, 2009

    <p>2 other things to add as they were just remembered by the community:</p>

    <p>*) We should versionize the manual... actually within the homepage we always refer to the latest trunk which is not the release.</p>

    <p>Also old manuals can not be found. It should be possibleto have the manual for each release (main release would be great) available through the homepage. Having a link which leads to the releases of 1.5, 1.6, 1.7, Next minor release (trunk) and so on</p>

    <p>This would also mean that we would have to think of branching the manual because the actual strategy to build always from trunk is very problematic... it's not good always to add "with release 1.7.6 you can do this... with 1.8 that....".</p>

    <p>*) We should also cover the API-doc within the build process... actually it seems as if the API doc is always forgotten and outdated. As API-doc is also a sort of manual, it seems to me that it should also be a part of this manual proposal.</p>

  7. Jul 16, 2009

    <ac:macro ac:name="note"><ac:parameter ac:name="title">Zend Framework Acceptance</ac:parameter><ac:rich-text-body>
    <p>This proposal is approved for development in the Standard Library immediately<br />
    following the release of 1.9.0. This is an incredibly well considered and<br />
    detailed proposal, and covers a variety of concerns. Several items are not<br />
    approved, but the majority are. The details are as follows:</p>

    <h4>Quickstart translation: Approved, with additions.</h4>
    <p>For this to work, we need to re-organize the manual even more. Our thoughts on this is that we would have the following top-level items:</p>
    <ul>
    <li>Introduction</li>
    <li>Installation</li>
    <li>Learning Zend Framework
    <ul>
    <li>Quick Start</li>
    </ul>
    </li>
    <li>Reference</li>
    <li>Current manual</li>
    <li>Appendices<br />
    This would keep the initial page of the manual cleaner, allow for us to create official tutorials that could be translated (under the "Learning Zend Framework" section), and overall simplify the structure.</li>
    </ul>

    <p>This feeds directly into the "Cut files by sect2 instead of sect1" item as well, and we would like to combine the efforts there. </p>

    <p>The Zend Framework team will come up with the top-level items after discussion internally, and then we can proceed.</p>

    <h4>"Simplification": Approved</h4>
    <ul>
    <li>Centralized figures, compilation process</li>
    <li>Syntax highlighting in HTML</li>
    <li>PDF rendering with syntax highlighting</li>
    <li>CHM rendering</li>
    </ul>

    <h4>Having same manual.xml.in for all languages: Approved</h4>

    <h4>Put all xinclude statemetns in manual.xml.in: NEED MORE INFORMATION</h4>
    <p>Unsure how this ensures that all languages contain all files. Could one of you elaborate on this point some more?</p>

    <p>The files all need to be in the tree anyways, so we can easily tell if any files are missing, even those from xincludes – all files are separate in the source...</p>

    <h4>Snippets for translations: Approved</h4>

    <h4>Shared examples: Approved</h4>

    <h4>Rewrite building process as a Zend_Tool provider: Pending</h4>
    <p>We would like to test it out first to see what the memory and processing requirements are. If they are better than using the docbook toolchain, we'll approve it.</p>

    <h4>Adding index: Denied</h4>
    <p>While an index may be nice for local installs or printed manuals, for an online, searchable manual, it's a lot of effort for basically no return.</p>

    <h4>Modify manual translation status: Approved</h4>

    <h4>Setup documentation review: Approved...</h4>
    <p>We actually review documentation prior to moving to trunk. The main area where we would need additional review would be when docs are added to existing components by non-native English speakers.</p>

    <h4>Testing documentation examples: Approved</h4>
    <p>Linting only, however. We need to have automation on it, and this can be achieved by using XPath to search for all listings marked with language "php". </p>

    <h4>Documentation Standard: Approved</h4>
    <p>Matthew will add this for the 1.9.0 release.</p></ac:rich-text-body></ac:macro>