...
| Warning |
|---|
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 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.
...