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 also separate structure and semantics from presentation as much as possible. For these reasons neither HTML, Wiki markup, nor Microsoft Office are suitable. The DocBook project, which provides a mature DTD and XSL stylesheets for conversion to HTML, and which is supported in numerous other tools, is the leading contender for now. Some XSLT work may be required, however, to turn the document source into all the forms that may be needed.
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.