Documentation Guidelines

Ensure information is accessible (tables, lists) and annotated correctly. Diagrams/Table require titles (future work) and some call-outs (i.e. Architecture diagram).

The TOC is Title Case. Title Case on titles and top level subsection titles (H1 and H2 levels). The navigation panels will render All other headings (H3-6) are Sentence case to.

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 the italics with bold - less brain context switching to decipher italic. All programming snippets must be formatted as code or code blocks.

Use simple words (less than 5-6 syllables). Shorten sentences or break into 2 sentences to ensure conciseness. See style guides below for more details.

All landing pages (H1 top level sections) need introductory paragraph and explanation of what each 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)

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 (stupid 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. This is not to code or coding blocks. 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 all have a line space after them before the first paragraph. H1, H2, H3 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 - z is used instead of s in words like authorization vs authorization. By matching/spelling our words as the same supporting docs like RFCs, websites, and the software, our readers' comphrehension. The reader’s not trying to decode what terms are the same or if 2 terms spelt differently mean the same thing such as 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.