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.
nothing more than Clay's private opinions right now - some working principles |
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.
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: