Documentation Project Plan

The managing of OpenACS documentation has evolved through a few phases. This is a draft plan for the current phase that we are beginning. Please direct any comments about this plan to the OpenACS Development forum (or in context with the appropriate wiki page ;)

Background

Goal

to write superb documentation, so that users, developers and administrators of OpenACS installations can enjoy working with and using the system (with fewer headaches! =)

Scope

API Documentation: there are no plans to move the API docs to XoWiki. That ought to remain as is.

DocBook docs at: http://openacs.org/doc/index.html need significant work done.

Requirements

Requirements is about setting specifications and milestones we can verify, and includes exploration of scenarios, use cases etc.

Here are documentation requirements for:

• en:docs-end-user-reqs includes Marketing documentation requirements and Package documentation requirements
• en:docs-admin-reqs
• en:docs-install-reqs
• en:docs-dev-tutorial-reqs
• en:docs-eng-reqs

Available resources

• volunteers dedicated to regularly managing and updating the documentation
• other volunteers who contribute arguably more valuable documentation less frequently (such as magazine articles ;) (and may need some assistance etc. to have their work fit into docs well.)
• openacs.org website, including use of xowiki
• open-source software, text editors, spell checkers, html code validators etc.

Approaches in docs management explored

Strategy

Strategy is about creating an approach to doing work. It guides behavior and tactical decisions on the work effort.

Shape ongoing documentation efforts by using principles of continual improvement to re-engineer documentation production and management.

OpenACS documentation development is subject to the constraints of the software project development and release methods and cycles (the section called “Using CVS with OpenACS”). Essentially, all phases of work may be active to accommodate the asynchronous nature of multiple subprojects evolving by the efforts of a global base of participants with culturally diverse time references and scheduling idiosyncrasies.

The documentation strategy is to use project methods to involve others by collaborating or obtaining guidance or feedback (peer review) to distribute the workload and increase the overall value of output for the OpenACS project.

Work Breakdown Structure

Is about explicitly stating the way to implement the strategy as a set of milestones and the methods to use.

Status: this is a draft document, so there is no consensus on a WBS at this time. See en:Documentation_Project_Discussion for current activity.

Verification

This is where we measure how well this plan was implemented. Success is measured by A) verifying if the project has met the established goals and requirements, and B) reviewing for ongoing problem areas etc. Observations then help to modify the plan for the next documentation revision.

OpenACS follows verification through different means on different projects, but in all cases, the OpenACS community verifies the project as a success through feedback including bug reports, user and administrator comments, and code changes.

Related links and sources

• en:Documentation_Project_Discussion
• en:wikidoc-notice
• [en:Structure_Ideas]