Documentation Guidelines

Accessible documents allow everyone to access information equally. This also improves the user experience. To improve accessibility, use clear headings, descriptive alt text, and high colour contrast. This supports assistive technologies and aids users with visual or hearing impairments.

Make your information easy to read by using clear tables and simple lists. These formats act like a map, helping your reader navigate complex data quickly.

Give every diagram and table a descriptive title. For technical drawings like engineering diagrams, add call-outs to explain key parts. These labels guide the eye and clarify how systems connect.

Follow the other design rules in this document to improve your layout. Use consistent fonts, proper spacing, and organised headings. These elements work together to create a professional look. Structured formatting helps lessen eye strain and keeps readers focused on the content.

Pick the admonition type by what happens to the reader who ignores the box, not by how much we want their attention. Overusing WARNING trains readers to skip all five.

Keep an admonition to three sentences. Anything longer belongs in body text under its own heading.

Never stack two admonitions together, as readers skip both. Never open a section with an admonition, because the reader has no context yet for the thing they’re being warned about.

Use Title Case for all Table of Contents (TOC) entries to ensure clear organisation.

Use Title Case for your main titles and top-level headings, such as H1 and H2. This consistency helps readers navigate your document like a map. Ensure navigation panels match the H1 and H2 headings on selected pages to avoid confusing users.

Use Sentence case for all smaller headings from H3 to H6. This style follows a regular sentence. Only the first word and proper nouns are capitalised. This shows the reader that these sections provide supporting details, not main topics. The documentation needs varying heading styles to guide the reader through the content.

Use a collapsible block for very large code snippets, programming examples, debug outputs, or anything longer than 20 lines. This allows us to place more information on one or two pages, and readers can select exactly the information they need by expanding sections.

A collapsible block is an example block (==== delimiters) marked with [%collapsible]:

Always give the block a title, as the title becomes the text the reader clicks to expand. A block with no title shows the word "Details" instead, which tells the reader nothing about what’s inside.

The exception is a code block (more than 20 lines) that a user needs to copy. Keep the text or block expanded.

Use a clear font that is 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).

Avoid capital letters BECAUSE IT SEEMS LIKE WE’RE ALWAYS YELLING AT OUR READERS! Use bold to emphasise or italics (sparingly) to highlight information. Use capital letters for all acronyms such as TCP/IP and EAP.

The CSS files set the font family and size for every page, see Layout and CSS.

Use bold to emphasise information rather than italics, because readers recognise bold text faster than they recognise italic text. All programming snippets must be formatted as code or code blocks.

Code blocks using a source such as html, shell (zsh, bash), and unlang render the output text in different colours. Since there are so many sources, we’re allowing all types and will update CSS with final colours for the output text.

Other code blocks without a native source, keep text in the code or code block black.

The CSS files control every colour on the page, see Layout and CSS.

Replace words of six or more syllables with shorter terms that translate easily. Substitute or remove formal words not recommended for software documentation. Check the Terminology section for more information on recommended words and terms.

Shorten sentences or break them into two sentences to ensure conciseness.

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

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

Left-justify (irregular right edge) all pages. A left-justified page is more accessible and increases readability. Avoid centre-justification.

The CSS files control the design elements: fonts, colours, layout, margins, and page size. Change one line in a CSS file and the change applies across every page at once.

Headers and footers live in separate files, which keeps branding and navigation consistent. Update a logo or a contact address in one header file and the change reaches every page.

Remove as many gerunds (words ending in ing) as possible. English doesn’t easily translate these words. This can confuse non-native speakers.

Check convoluted text or run-on sentences with Hemingway or Grammarly editors. The reading level should be Grade 9. This ensures the document is scannable and readable. Most users can understand what they’re reading on the first pass.

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

This is not applicable for code or code blocks. These numbers need to stay in their native formats.

Decimal numbers need to only be two significant digits.

See IEEE expressing numbers for more guidance.

Currently, there is one space after a period at the end of a sentence. The source files still hold a mix of one and two spaces, and this will change in a future release. Use the Oxford comma to make sentences clear and concise.

Choose the list type to match the content:

Use a period at the end of each list entry.

All headings have a line space after them before the first paragraph. There is also a single blank line between paragraphs.

The recommended method is to use one space at the end of a sentence (see the previous note in Punctuation).

Heading spacing is set per page rather than globally in the CSS.

We use British or UK spelling and most words use the s instead of z. An example is "utilise" versus "utilize". By spelling our words the same as the supporting material, for example the company website or the FreeRADIUS software, our readers' comprehension increases. The reader isn’t figuring out what terms mean if they’re spelled the same. They’re also not determining whether two terms spelled differently mean the same thing.

Exception: Use the z form for authorization rather than authorisation. This rule matches the same spelling of the term authorize in the RFCs and codebase.

Put information in tables where applicable to increase readability / scanning. See Collapsible text for hiding very long code snippets, programming examples, or debug outputs.

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

Remove all slang terms and rhetorical questions. 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 localisation.

Use xref: for a target inside our documentation and link: for a target on another site.

Don’t send an external URL through xref:. Asciidoctor treats the URL as an anchor name and emits href="#https://example.com/", so the link looks right on the page and goes nowhere when clicked.

To print a macro instead of running it, wrap the example in plus signs inside the backticks:

Always put link text inside the brackets. Empty brackets print the raw URL, which readers can’t scan and screen readers read out one character at a time.

Every module needs its prefix when you reference a file in a different module. A page in howto linking to a page in concepts needs xref:concepts:, and leaving the prefix off resolves against howto instead.

RFCs need to be referenced with no dash between RFC and the xxxx digits. For example, RFC 2865.

Use the built-in functions and templates from AsciiDoc to standardise output rendering.

Some tips include:

Add partials for any section of text repeated more than twice throughout the documentation. Some examples are the mailing and RFC lists that are repeated multiple times throughout the documentation.

Any paragraphs or text that is required in more than one place needs to be placed in a partials directory.

Any diagram or image that is required in more than one place needs to be placed in an images directory.

Industry-standard acronyms use capital letters.