Style Guide¶

The style guidelines exist to keep the documentation clear and understandable.

Choose the right title¶

Use a short, keyword-rich title that captures the intent of the document and draws the reader in. Ensure that the title clearly and concisely conveys the content or subject matter and is meaningful to a global audience.

The text for the title of the document must use title case. Capitalize the first letter of every word except conjunctions and prepositions.

Use sentence case for headings¶

Use sentence case for the headings in your document. Only capitalize the first word of the heading, except for proper nouns or acronyms.

Use present tense¶

Use active voice¶

Use simple and direct language¶

Use simple and direct language. Avoid using unnecessary phrases, such as saying "please."

Prefer shorter words over longer alternatives¶

Address the reader as "you"¶

Avoid using "we"¶

Using "we" in a sentence can be confusing, because the reader might not know whether they're part of the "we" you're describing.

Avoid jargon and idioms¶

Some readers speak English as a second language. Avoid jargon and idioms to help make their understanding easier.

Avoid statements that will soon be out of date¶

Avoid using wording that becomes outdated quickly like "currently" and "new". A feature that is new today is not new for long.

Create useful links¶

Don't use here, click here or URLs as the text for a hyperlink.

There are numerous articles explaining what makes a good hyperlink , but fundamentally the "Don't" examples above:

1. Decrease the overall usability of links.
2. Decrease the overall accessibility of the links.
3. Decrease search engine performance and content find-ability.

Raise an issue or comment below