= Trac Documentation

== 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 [http://python.org Python], we adhere to [pep:0008 Python's PEP guidelines].
Code documentation can be viewed at the 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 [gforum:trac-dev 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 [googlegroups:trac-users:3c2098f16077816d this message] and should provide a starting point for Trac documentation contributors.

Some of the needs:
 - Tutorials
   - 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