Writing Documentation

Here are some guidelines to help write consistent documentation.

Docstrings

Docstrings are like definitions. A documentation string can start with a noun phrase that defines what is being documented (e.g., "A generalized version of partition.").

In sentences where the subject is the value being documented, you may elide the subject. "Returns the documentation of the given value." is preferred over "doc returns the documentation of the given value."

Generally:

• Use the present tense.
• Capitalize.
• Punctuate.

And remember, true and useful documentation with an inconsistent style is better than no documentation at all.