Documentation Team

{note:title="Master" manual}The English version of the manual is the "master" document from which other languages are translated. All translation members are encouraged to help improve and add (e.g. examples, FAQ) to the English manual. Improving the quality of the content helps reduce support requests sent to the list, and results in more successful and enjoyable deployments by developers new to the ZF.

Adding substantial deviations directly to the translations would in effect create multiple master documents, and staying in sync becomes a nightmare quickly. Instead, where translators discover improvements can be made (there is plenty of room!), these should be either made directly to the English manual, or added as new [JIRA|http://framework.zend.com/issues/secure/Dashboard.jspa] issues for the English manual. Teams simply continue to track changes to the English "master" version for translation.{note}

{toc}
h1. Teams introduction
h2. Documentation Team

The ZF documentation team helps with tasks and projects affecting all versions of the manual. Many tasks require only basic English skills, so we *strongly* encourage participation by everyone. All documentation team members are also encouraged to help with the English manual. Many edits, improvements, example contributions, and merging of user-contributed comments do *not* require strong English skills. Content and accuracy are much more important than "perfect" English, and English experts can adjust wording as needed later.

The documentation team has the authority to edit the English manual. Documentation project team members include:
* All Translation project members

h2. Translation Teams

Each translation team gets his own wiki page. On these pages the team can list its members and resume where the team is needing help, e.g. We encourage people to communicate in whatever language they prefer. The language translation team wiki pages support UTF-8, including Japanese and Chinese. Translation teams include:

{children:page=Documentation Team}


If you see this "[~nocla]", then please ask that person to [send a CLA|http://framework.zend.com/wiki/x/xgE] before contributing.

h1. Help wanted
h2. "Wikification" of the Manual

We have documented numerous cases and examples where the current process imposes too many hurdles, complications, and effort for those wishing to use it and contribute. Since the vendor of our current wiki successfully uses their own product for their manual, including generating the PDF and HTML, we would like to consider the implications of switching from authoring content in docbook to using our wiki.

We are proposing opening up the English documentation process to participation by all documentation team members, and allowing wiki page commenting by anyone, but with reasonable moderation by the documentation team members, following in the footsteps of wikipedia. In order to help achieve consistency, we are also proposing borrowing [mozilla.org's|http://www.mozilla.org] documentation style guide, subject to exceptions you might recommend (hint).

The process for adding content and editing the ZF manual pages might benefit from the use of a wiki that allows user-contributed comments. How many times have you wanted to make a suggestion or change to the English manual, but not done so?

h3. Milestones

* Make a PDF and HTML copy of the manual available for download.
* Make smaller edits easier, and possible by at least everyone on the documentation / translation teams, possibly including all CLA signers.

1. Click the "Edit" tab for the page
2. Select all and copy the wiki markup
3. Paste it into my text editor

\\
In this way, one can work on the wiki pages offline when needed.
Edits from different authors can be merged using the wiki.
{quote}
* Quick access: type [http://framework.zend.com/zend_controller] similar to php.net, where you can easily access a specific function by appending it to the url
* Unreleased incubator documents should be avaiable in wiki, but not added when extracting to HTML and PDF (Maybe tagging or a seperated wiki space).
* Some contributors are writing like "this function can handle xxxx" other as "you can handle xxxx with this function"... note the first person stlye... a defined write style is *must* and makes the document flow smoothly as a whole.
* Automatically generate HTML and PDF for each language, either directly from the wiki, or from docbook, after auto-generating docbook from the wiki.

h3. Tasks
* Study [http://confluence.atlassian.com/x/8hIC] information on features, including the user manual
* Research plugins and current efforts to export the wiki to docbook. [http://confluence.atlassian.com/display/CONFEXT/Home]
* Research possibility of tagging pages, such that a PDF could be created from tagged pages.
* Consider adding "edit last comment" to our issue tracker (Jira), and search for a way to do so with our wiki (Confluence).
** [http://confluence.atlassian.com/x/DMwC]
** [http://confluence.atlassian.com/x/TC0]
* Decide on moderation process / policy for comments.
* Provide feedback to an example docbook to wiki converted page: [http://framework.zend.com/wiki/x/9hE]
* Provide feedback to an example new wiki homepage: [http://framework.zend.com/wiki/x/ahI]

h3. Process Mechanics

The purpose of the wikification includes removing the need for any of us to write docbook.

1) Docbook to wiki import (one time only)
2) Translators and english manual authors use the wiki to author content, but they should restrict and limit themselves to the basic wiki markup already found in the wikified manual pages.
3) All CLA signers use the wiki to comment
4) Translators and english manual authors review comments, sometimes deleting comments and merging comments with the wiki page content
5) Wiki to docbook export (every time we make a release of the ZF)
6) We use normal docbook to HTML/PDF process to publish updates to http://framework.zend.com/manual
7) If we can export the wiki to HTML/PDF and they look as nice as #6 above, then we can use the HTML/PDF created by the wiki to HTML/PDF process. The wiki to HTML process could be either something custom, using Zend_Pdf, or using Confluence export. However, we still don't want to lose the ability to convert back to docbook, just in case we need the docbook formatted version of the manual for some other reason. To keep this ability and make wiki to docbook conversion easier, wiki authors must not use "fancy" wiki markup (use only basic tags that are already used in wikified manual).

Please enter our brainstorm time, where we can openly consider all ideas to help synthesize a final proposal, before decisions are made.

For the mechanics of this new process, we could setup *two* new wikis. One would contain the last official release for public viewing and commenting. The other would be a draft, work-in-progress with comments rolled into the body of the page before pages are "released". When we prepare for a release, changed pages could be copied to the official release wiki. Then, translators could use the wiki "difference" feature to see what has changed in the English manual on the release wiki, without seeing all the interim edits made in the draft wiki.

There might be a wiki plugin that allows tagging and viewing differences between tags ( [http://confluence.atlassian.com/display/CONFEXT/Home] ). If so, such a feature/plugin might eliminate the need for having two wikis. I am not eager to consider using a different wiki, as it would significantly complicate user account administration and logins. The current wiki already supports UTF8 text.

Our current wiki system supports export to PDF and HTML, although the exports are "plain", and might require some creative manipulation, such as using Zend_Pdf to beautify it. I agree entirely with recent posts about the value of providing HTML and PDF downloads for the manual. Several questions remain, including the docbook import/export process for our wiki (Confluence).

Also, incubator components using the wiki for documentation would make documentation available immediately, without requiring the curious to go through the process of "building the manual". Many of us would like to help with documentation for the new incubator components. Group editing of a wiki page has advantages over trying to coordinate editing of the documentation via SVN.

h2. Wiki Maintainers

The [ZF Sidebar|http://framework.zend.com/wiki/x/Mwc] helps greatly, the organization and look and feel of our wiki pages could be improved. [Drupal's|http://drupal.org/] website demonstrates an orchestrated, planned arrangement and organization of content. Their content is somewhat similar to that found in the ZF wikis, so perhaps we can borrow some organizational ideas.

We are looking for volunteers to proactively define this team's mission, responsibilities, and tasks.

h3. Responsibilities

# Managing: [http://framework.zend.com/wiki/display/ZFUSER/Home]
# Maintaining site maps for each wiki space
# Provides recommendations for changes to ZFDEV, etc. wiki spaces

h3. Milestones & Tasks

# Improving organization of wiki
# To make sure users can easily find what they are looking for in our wiki
# Bring logic structure in every page, and set some standards
# Site Maps

h2. Documentors
Currently the I18N team is looking for your help. They are looking for people to document the already commited code, write examples and use cases. Interested? Please [Subscribe to fw-i18n|mailto:fw-i18n-subscribe@lists.zend.com] and [send a message|mailto:fw-i18n@lists.zend.com].