Handbook style guide

Handbook contributors should follow this style guide.

Links

When linking to a GitHub resource, use HEAD instead of a specific branch, tag or commit.

When linking to the standard’s documentation, use the latest version instead of a specific version.

Structure

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

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

Hint

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

Note

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.

Warning

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.