Documentation Standards

Owned by Former user (Deleted)
Last updated: May 10, 2006Version comment
2 min read

The Need for Documentation

Documentation for an open source project is a fundamental community need. It paves the way for both new users and contributors to join the community, and is an essential communication for distributing technical expertise.

Documentation Format (working principles for Release Docs)

nothing more than Clay's private opinions right now - some working principles

  • Documentation source should be in an open format which may be readily published in a variety of other formats - HTML, Plain Text, PDF, etc.
  • It should separate structure and semantics from presentation as much as possible.
  • It should be easy for developers to write, or volunteers to contribute, without a significant learning curve.
  • There should be some mechanism or venue for ongoing review and comment (i.e. this wiki) without introducing a significant maintenance burden.

For these reasons neither HTML, Wiki markup, nor Microsoft Office are very suitable. The DocBook project, which provides a mature DTD and XSL stylesheets for conversion to HTML, and which is supported in numerous other editor tools (including Microsoft Office and some Eclipse plugins), is the leading contender for now. It is, however, more complex than is needed, and some XSLT work may be required. So it is not yet the ideal solution, but seems to be the best option.

Proper use of this Confluence Space

The danger this space must take into account is the potential confusion that may be caused over having documentation available both here and in other locations. This space is an attempt to harness the advantages of having a place for easy review and comment without muddying the waters. Some guidelines are required:

  • If any of these pages duplicate content provided elsewhere (e.g. docs/architecture) they should, as a general rule, hold the identical content. This will be a maintenance cost, but it purchases the refinements that come from a more ready peer review.
  • When any of these pages goes out of synch with documentation labeled elsewhere (e.g. when pages are in a state of active editing or revision) they must clearly be identified as such at the top of the page.