- next
- previous |
- ZTM »
- Documentation »
- Styleguides »
Documentation guidelines¶
“The first draft of anything is shit.”
— Ernest Hemingway“What is written without effort is in general read without pleasure.”
— Samuel Johnson
Documentation should be beautiful.
All hand-written documentation is processed by Sphinx and therefore written as reStructuredText (rST). Please read the reStructuredText documentation.
API documentation is generated by the standard zope.apidoc module.
Differences between operating systems¶
Show the Unix approach, but always with a footnote to the Windows approach
Be realistic¶
If it took a month to write you will not be able to document it in an afternoon.
Learn to love the writing process! Rejoice at finding fancy formulations.
Documentation strings¶
Documentation strings or docstrings are formatted as described by :PEP:257 and :PEP:287.
Improve usability¶
If something is difficult to describe, perhaps your time is better spent improving the usability of the functionality?
When to use the different spellings of Topic Maps¶
We try to follow Lars Marius Garshol’s recommendations
Sections¶
reStructuredText supports sections in the text using underlining and overlining. In the documentation for Python they have tried to use the following convention <http://sphinx.pocoo.org/rest.html#sections>:
- # with overline, for parts
- with overline, for chapters
- =, for sections
- -, for subsections
- ^, for subsubsections
- “, for paragraphs
Document incorporated code¶
If you incorporate some code, meaning that you copy files from other projects or with special licensing into the repository, you must list it in the README.txt AND in the documentation.
(This is not required if you simply use a library from PyPI through setuptools, though it doesn’t hurt to document dependencies.)
Although we have sinned against this in the past, it is nice to let the author know that you used it.
See the exim documentation for a nice example of how to do this.
Spelling¶
Most of the current documentation has not been written by native English or American-English speakers. If there are any idioms, misspellings or other nuisances please let us know.
And please run the documentation through a spell-checker before committing.