Help Style Guide

The help texts displayed in the help browser are formatted as GitHub Flavored Markdown. GitHub Flavored Markdown is documented here: https://github.github.com/gfm/

This style guide is mostly meant for help text authors to ensure that we keep a consistent look and feel between authors.

Note

Markdown support in the help browser is a relatively new feature and this style guide is most likely incomplete. We are expanding this style guide while we are going.

Headings

Most entries in the help browser are short and do not require any headings. If headings are needed, we prefer ATX Headings. The largest heading that should be used is a third level heading (### Heading).

An example for the usage of headings can be found in the “Strategy and Tactics” help entry.

Unordered Lists / Bullet Points

The preferred marker for bullet points is the asterisk (*). Although the dash (-) might feel more natural, programmatic generated help texts mainly use * and we aim to be consistent.

Links and References

The help text can contain external links, like the “Strategy and Tactics” help, that links to a prettier formatted online version.

Links to anchors in the help text itself or other items in the help browser are not supported. When referencing other help sections or items, we use emphasized text. The emphasized text should be the heading of the relevant section or the name of the referenced help item.

Admonitions

Admonitions are not supported. We emulate the effect by using emphasized all-uppercase emphasized admonition labels (e.g. *NOTE:*)

Formulas and Literal Values

For inline formulas or literal values, we use code spans by wrapping them in backticks.