Basic Guidelines¶
Note
The community driven documentation is being migrated to a sphinx-based setup. This tutorial needs to be updated accordingly.
About our editoring policies, preferred documentation format and content licensing.
Overview¶
The Documentation section of the Grok web site welcomes your contributions. We welcome any documentation that another Grokker may find helpful.
You will need to register with this web site before you can contribute. A person in the Documentation group will review your content it publish it. The Documentation group is also a very open group, so if you’ve contributed some content please ask a Grok web site person and they’ll add your account to the Grok Documentation group. This will give you full permissions over the Documentation area of the Grok web site.
There is an effort to maintain community documentation that was announced on the mailing list:
Content Types¶
We have two main types of content you can add to the Documentation section right now:
- Create a How-To. A single page of documentation. Bite-sized help that should focus on a single task.
- Create a Tutorial. A multi-page work of documentation. If you are tackling a sizeable asset of documentation, then we recommend that you use the Tutorial content type even if you only write a single page to begin with. The Tutorial is useful if you later want to add pages that are only example code, or want to expand your documentation into a more complete work.
In a few places on the documentation area we currently dislpay “How-To” or “Tutorial” but we may remove these at a later date, since people browsing through documentation will only be interested in navigation by topic or audience and not by content-type.
ReStructured Text¶
The preferred format for documentation is using ReStructured Text (ReST). You can enable this for your account by going to “Preferences” -> “Personal Preferences” and choose “Basic HTML textarea editor”.
If you do not know restructured text, it’s a standard Python documentation format that allows you to apply structure to plain text. The ReStructured Text Primer serves as a quick introduction to the format. Also the ReST Extensions page will tell you how you can format your ReST documentation so that source code will have line numbers and syntax highlighting applied to it (yummy!).
While ReStructured Text is our preferred format, if you are only comfortable working in a WYSIWIG editor such as Kupu or already have documentation in HTML format we still welcome your contribution to the site. Our site editors may later on convert HTML into ReStructured Text format where appropriate.
We may take selected content in ReStructured Text format on the web site, and include this as part of the Grok package itself inside the /doc/ directory for the convenience of developers who prefer to access documentation in plain-text.
Documentation Web Site Bugs¶
There are currently a couple of small bugs in our web site that you may run into. We intend to fix these bugs, but for now ...
When making subsequent edits to ReStructured Text formatted documents, please take care this format is selected before you hit “Save”. There is bug with the web site at the moment where it defaults to Plain Text.
You are also prompted for a Format for the Summary field. This field must be plain text. The Summary field is displayed in lots of areas other than the web page, such as RSS feeds, search engine results and other contexts where the only format is plain text.
Editing and Comments¶
Any documentation which has typos or incorrect information is free to be corrected by anyone in the Documentation group. In addition, members of the Documentation group may incorporate or respond to comments made to documentation to better clarify or improve existing documentation. We will remove comments from the site after we incorporate them into the main body of the text.
