Documentation Guidelines

Accessible documents ensures equal information access for everyone and improves the user experience. Accessible design benefits all users by making information clearer and easier to understand. This means making documents usable by assistive technologies and navigable for all users.

Ensure information is accessible (tables, lists) and annotated correctly. Diagrams/Table require titles and some call-outs where required. (i.e. Architecture diagram). Other suggestions are outlined in this document that include fonts, spacing, headings, etc.

The TOC is Title Case. Title Case on titles and top level subsection titles (H1 and H2 levels). The navigation panels should render the same title heading (H1/H2) as the selected page(s). All other headings (H3-6) are Sentence case.

Use a clear font that legible on-screen and large enough so it’s easy to read (accessible). Generally a non-serif font is best for screens and works in PDFs (if required)

It’s advisable to remove CAPS BECAUSE IT SEEMS LIKE WE’RE ALWAYS YELLING AT OUR READERS - use bold to emphasize or italics (sparingly). Use CAPS for all acronyms such as TCP/IP, EAP etc.

Try to use bold to emphasize the information rather than italics; there’s less brain "context switching" to decipher the fonts bold versus italic. All programming snippets must be formatted as code or code blocks.

Code blocks using source such as ruby, html, shell (zsh, bash) colourises the text. Since there are so many sources, we’ve opted to remove them and keep text in the code or code block black.

Use simple words (less than 5-6 syllables). Substitute/remove formal words not recommended for software docs. Check Terminology section for more information on recommended words and terms. Shorten sentences or break into 2 sentences to ensure conciseness.

All landing pages (H1 top level sections) need introductory paragraph and explanation of what the section contains.

Add xrefs to all the subsections contained in theis section on the top level landing page. Users can select a topic from main page while reading or use the navigation panel on left side.

Ensure all pages are left-justified (irregular right edge) makes the document more accessible and increases readability. Avoid centre-justification.

CSS files control the margins and page size.

Remove as many gerunds (words ending in ing) as possible - english doesn’t translate the words easily and these verbs are confusing to readers who’s first language is not english.

Check convoluted text or run-on sentencces with Hemingway or Grammarly editors. The reading level needs to be Grade 9 to ensure that the document is readable, and every user (limited inteliigence or not) can understand what they’re reading on the first pass.

Numbers like 1,2,3,…​up 9 are written as words. Numbers starting at 10+ are written out in numerals.

Decimals numbers need to only be 2 significant digits.

See IEEE expressing numbers in documentation for more guidance.

Use the Oxford comma to make sentences clear & concise. Lists use periods at the end of the sentence entry. Use unordered lists when listing contents, or items. Use ordered list for tasks or steps.

All Headings have a line space after them before the first paragraph. H1 and H2 headings need 2 line breaks before the following paragraph - TO DO the CSS file and update heading spacing as a global change. Spacing of 1 line between paragraphs. Only one space at the end of a sentence is required.

International English - s is used instead of z in words like authorisation vs authorization. By matching/spelling our words the same as supporting docs, e.g. company website or FR software, our readers' comphrehension increases. The reader isn’t decoding what terms are if splet the same, or if 2 terms spelt differently mean the same thing. An example is authorise versus authorize.

Put information in tables where applicable to increase readability / scanning. Use collapsible widgets for very large code snippets/programming examples/debug outputs or anything that is longer than 4 lines. This allows us to place more information on 1 or 2 pages and readers can select exactly the information they need by expanding sections.

Friendly and informal for users that need to feel comfortable when accessing information. The informal tone allows the use of contractions.

Remove all slang terms, remove rhetorical questions. Replace humongous words with smaller easily translated items. Check other style guides (Chicago/Google/Apple/Microsoft) for anything else not covered by this page. MS Tips is a good reference for technical documentation and localization.

RFCs need to be x-ref’d and no dash between RFC and xxxx digits. For example, RFC 2345

Use the built in functions and templates from ascidoc to standardize output rendering. Some tips include:

Add partials for any chunk repeated more that twice throughout the docs Some examples are the mailing and RFC lists that are repeated multiple time throughout the doc. Any diagram or image that is required in more than one place needs to be placed in a partials directory.