Question 1: In Confluence or in the source tree?
Well, it's sometimes hard. So here's the guideline:
- If the piece of documentation is useful to a non-developer who uses/administers an instance of SIO2, it should be in Confluence.
In Confluence we have some redirecting pages. To edit such a page, enter its URL with #noredirect appended. The redirect will be disabled.
Question 2: How to write documentation in the source tree?
This documentation resides in the code and in folders doc/rst and sioworkers/*/rst.
Follow reStructuredText Primer and be consistent.
This documentation goes through our standard creating a change workflow.
Question 3: How to write documentation in Confluence?
Well, use common sense and write short articles. Try to be as attractive, as possible.
At the moment there is no convenient way for external contributors to edit our documentation.
Please forgive us and leave propositions on what to change in the comments!
- Creating diagrams with Gliffy is übereasy (use the Insert/Edit Macro button in Wiki Markup Editor and look for Gliffy).
- Know the lozenge macro (renders a nice huge button, like in Reporting Bugs and Ideas).