Changes between Version 13 and Version 14 of SeaChange/DocumentationRequests

Timestamp:

Feb 21, 2015, 4:58:28 PM (9 years ago)

Author:

figaro

Comment:

Added documentation guidelines and removed section which was out of date and irrelevant

SeaChange/DocumentationRequests

@@ -1 @@
-= Documentation Trac Users Badly Want =
+= Trac Documentation
 
-This page collects documentation topics that users want, and are not sufficiently covered by the TracGuide. It was triggered by [googlegroups:trac-users:3c2098f16077816d this message], and should provide a starting point for people who want to contribute documentation to the Trac project.
+== Wiki documentation guidelines
 
+An 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 of 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 however 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 also adhere to [https://www.python.org/dev/peps/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 [https://groups.google.com/forum/#!forum/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:
@@ -10 +31 @@
    - 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
 
-== Vote for a topic, or add your own ==
-Please:
- * Enter your username or email when editing this page. Anonymous changes may be deleted.
- * Feel free to add your topic in an alphabetical order. Mention any tickets showing that the topic is badly understood by users in the "Related tickets" column.
- * Only add +1 for your vote: these pages are monitored by Trac users and adding 100 to your favorite topic will be quickly detected. So __don't waste your and others' time with such a behaviour__.
-
-|| '''Topic''' || '''Votes''' || '''Related tickets''' ||
-|| TracDev/ApiDocs || 4 || #8695 ||
-|| Request processing order diagram || 1 || #8696 ||
-|| Redirect mechanism (RequestDone) || 1 || ||
-|| More Pictures! || 1 || ||
-|| HOWTO Move database to new server || 1 || ||
-
 ----
 See also: CookBook/About