Warning 2013/08/11


Please see the Orientation modules or the  User Documentation Plan  area the for more current information on contributing to Apache OpenOffice documentation efforts.

This page is about user guides for ordinary end-users of Apache OpenOffice.org. It summarizes the current situation regarding production of these guides: by whom, where, how.

The existing guides for OOo are Getting Started with OOo and guides for Writer, Calc, Impress, Draw, and Math.

A guide for Base is in incomplete draft and may need to be handled differently.

The Developers Guide, Programmers Guide, and Administrators Guide will be covered on a separate page.

From discussion on the ooo-dev list (under the subjects "User documentation planning", "Source format for user guides", and "Scope of Apache license: what needs to be covered?"), the current group of people producing end-user guides for OOo can continue producing those guides for AOOo using their own website (ODFAuthors.org) and their own processes and mailing list. The model for this is the way Apache Subversion is handling its user guide: http://subversion.apache.org/ (see the "Documentation" link in the side panel on left).

This arrangement could, of course, change as the AOOo project develops.

All members of the AOOo community are encouraged to participate in user guide production by writing, editing, reviewing, offering suggestions, or in any other way. See the OOoAuthors website for how to sign up for the mailing list and/or access to draft material on the website.

The guides are dual-licensed as GPL v3 and CC-BY v3, which is compatible with Apache licensing.

The source documents for the existing guides will remain in ODT and the finished documents (in ODT, PDF, and printed form) will be made available to users through links from the AOOo website to wherever the docs are stored. (Details on where that might be are yet to be worked out.) Other formats (e.g., HTML) could be added later.

Reasons for ODT as source format:

  1. ODT source enables us to publish guides in numerous formats relatively quickly and easily. This is what we're doing now. From wiki format, conversion to ODT and PDF (and other formats?) is possible but the results need a lot of manual tweaking to be of high standard.
  2. Using ODT files as source enables people to work on the user guides without needing to have Internet access while doing the work.
  3. Tracking changes during edit and review is easy using OOo's change tracking tools. Wiki "change tracking" is cumbersome and AFAIK one cannot accept or reject individual changed items; one can only revert a set of changes or re-edit the revision.
  4. For these reasons, the people who have been producing the OOo user guides over the years have expressed a clear preference for working in ODT, not wiki.
  5. Writing user guides for an office suite using any method other than the office suite itself strikes many of us as a very bad advertisement for one's product.

Reorganising Content

The current set of user guides evolved over several years as OOo community members contributed chapters to them. All books could be improved, and two in particular need serious consideration about length, organisation, and content. Proposed major content changes are discussed on the ODFAuthors list and will be included on this wiki for the convenience of other project members.

  • No labels