Changes between Version 14 and Version 15 of SeaChange/DocumentationRequests
- Timestamp:
- Feb 21, 2015, 9:04:54 PM (9 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
SeaChange/DocumentationRequests
v14 v15 3 3 == Wiki documentation guidelines 4 4 5 A n often requested feature is having better documentation. Adding documentation is one of the easiest contributions new developers and users can make and helps to promote the use ofTrac to a wider audience.5 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. 6 6 7 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 howeverthat we ask each contributor to adhere to:7 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: 8 8 * Be clear and concise: strive for uncomplicated text that clearly explains the concept; every sentence makes a single point. 9 9 * Be complete: provide the information from start to end, provide code examples, explain what the user will ultimately get, add a section on caveats. … … 11 11 == Code documentation guidelines 12 12 13 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 a lso adhere to [https://www.python.org/dev/peps/pep-0008/ Python's PEP guidelines].13 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 [https://www.python.org/dev/peps/pep-0008/ Python's PEP guidelines]. 14 14 Code documentation can be viewed at the ApiDocs. Your code contributions are automatically added to these Docs if they are copiously commented. 15 15 … … 19 19 * Refrain from using parentheses `()` if the point is equally valid without them, or use commas instead. 20 20 * Refrain from using the first person, such as 'I', 'we' or 'our'. Also refrain from using emoticons. 21 * If you are unsure about how to present your ideas, raise a thread on the [ https://groups.google.com/forum/#!forum/trac-dev TracDev mailing list].21 * If you are unsure about how to present your ideas, raise a thread on the [gforum:trac-dev TracDev mailing list]. 22 22 23 23 == User requests for Trac documentation 24 24 25 Some documentation topics that users have voiced a need for and are not sufficiently covered by the TracGuideare collected below. It was triggered by [googlegroups:trac-users:3c2098f16077816d this message] and should provide a starting point for Trac documentation contributors.25 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. 26 26 27 27 Some of the needs: