Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History
How to join the documentation and translation teams:
  1. [Zend Framework Contributor - Getting Started] - See #1 to #4.
  2. Follow our documentation style guide.
  3. Introduce yourself and interests by posting to the fw-docs mailing list.

Help Wanted

The wiki supports email change notifications (including digest mode). See the envelope icon in the upper right side of this page. Individuals can easily track progress for only the translations they care about. Much thanks to Ralf for getting this started.

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:

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:

Please sign CLA
If you see this "[~nocla]", then please ask that person to send a CLA before contributing.

Using this Wiki to Support the Teams

Wiki Web Tasks

Need Proactive People
Compare the organization of our wiki spaces (http://framework.zend.com/wiki/dashboard.action) to http://drupal.org/. Help wanted.

Although the ZF Sidebar helps greatly, the organization and look and feel of our wiki pages could be improved. Drupal's 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.

Looking for volunteers to proactively define this team's mission, responsibilities, and tasks.

Responsibilities

  1. Community manages: http://framework.zend.com/wiki/display/ZFUSER/Home
  2. Community maintains site maps for each wiki space
  3. Community provides recommendations for changes to ZFDEV, etc. wiki spaces
  4. ...

Milestones & Tasks

  1. Site Map
  2. Improving organization of wiki
  3. etc.

Goals / Motivation / Tasks

  • 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.
  • Reduce the learning curve and effort required to make edits to the manual and translations.
  • Allow anyone to comment on each section, but with comment moderation, so that the manual can evolve more quickly and with more flexibility than the current process.
  • Need notification system for edits (e.g. the wiki "watch"/notifications feature)
  • Follow a documentation style guide and proofread before it is released.
  • Need to support offline editing of content, ideally with a plain-text import/export capability. Alternatively:

    1. Click the "Edit" tab for the page
    2. Select all and copy the wiki markup
    3. Paste it into my text editor
    4. Save a copy as "page title.txt.orig"
    5. Save a copy as "page title.txt"
    6. Continue editing "page title.txt" [offline] until complete
    7. Review the diff of "page title.txt.orig" and "page title.txt", revising the latter as necessary
    8. Paste the revised wiki text into the wiki markup tab of the page editor, and save the page
    In this way, one can work on the wiki pages offline when needed.
    Edits from different authors can be merged using the wiki.

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

Process

Subject: Proposal: Major Change to Facilitate Participation with English Manual
Date: Tue, 05 Sep 2006 13:27:17 -0700
From: Gavin Vess <gavin@zend.com>
To: fw-docs@lists.zend.com

Greetings,

I would like to propose a change to how we write the English manual. I
think 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 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?

Details
==================
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.

TODO
======================
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.
http://confluence.atlassian.com/x/8hIC - information on features,
including the user manual (in their wiki)

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.

Cheers,
Gavin

Project Team Wiki Pages

Ralf wrote:

Any suggestion for improvement is highly appreciated. With a page for
each team the translation coordination could be visible for anyone
outside the team or mailing list. So people might decide to help when
they see some concrete tasks to do, like "Zend_Cache needs to be
translated to French" for example.

Ralf Eggert wrote:
> Hi again,
>
> another idea just came to my mind. We could even use the wiki for
> coordinating the translation work.
>
> 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.
>

> Ralf

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