Handbook style guide#

Handbook contributors should follow this style guide.


Unless a page is short, it should start with a description of its contents.

If relevant, a page should include a section on testing that describes the tests to verify work.


Admonitions (box outs) can be added using the hint, note and warning styles.


Use a hint admonition to share extra information that may be useful for a user of the documentation.


Use a note admonition to indicate that there are areas where the documentation requires further improvement, but this does not block use of the current information.


Use a warning admonition to indicate that the documentation on a page may not accurately reflect current practice, or that substantial caveats exist that should be noted before following the documented process.

Email addresses#

If an email address is discoverable on Google, there is no use in simple obfuscations like [at] and [dot] that make the text less readable. If an email address is not yet public, it is best to keep it that way than to attempt obfuscation.