Wiki documentation guidelines
A frequently requested feature is better documentation. Adding documentation is one of the easiest contributions new developers and users can make, and helps promote Trac to a wider audience.
Documentation is added as wiki content and the same wiki-principles apply. The quality of the documentation therefore relies on the self-organising ability of the community. There are some guidelines that we ask each contributor to adhere to:
- Be clear and concise: strive for uncomplicated text that clearly explains the concept; every sentence makes a single point.
- Be complete: provide the information from start to end, provide code examples, explain what the user will ultimately get, add a section on caveats.
Code documentation guidelines
A further feature that increases Trac's visibility as well as product quality is comments within the code. Given that Trac is written in Python, we adhere to Python's PEP guidelines. Code documentation can be viewed at the TracDev/ApiDocs. Your code contributions are automatically added to these Docs if they are copiously commented.
Do's and dont's
- Use headings to your advantage: a page can be more easily scanned by someone else if the sections are broken up with headings.
- Refrain from using parentheses
()if the point is equally valid without them, or use commas instead.
- Refrain from using the first person, such as 'I', 'we' or 'our'. Also refrain from using emoticons.
- If you are unsure about how to present your ideas, raise a thread on the TracDev mailing list.
User requests for Trac documentation
Some documentation topics that users have voiced a need for, and are not sufficiently covered by the TracGuide, are collected below. It was triggered by this message and should provide a starting point for Trac documentation contributors.
Some of the needs:
- cover basic things like - read option (but see TracDev/ConfigApi), show page
- Debugging Tools
- request tracer - see how a request is going to be processed or was processed (although not "dynamic", see the nevertheless enlightening TracDev/RequestHandling), which extension points were polled in which order and optionally with which parameters
See also: CookBook/About