Skip to main content Link Search Menu Expand Document (external link)
Spectrum Docs

Documentation Style Guide

Here you can find the standards we follow for writing, formatting, and organizing the Spectrum documentation. Please follow these guidelines and conventions when editing the documentation.

We use Nix and Just the Docs for building the documentation. Sources are written in AsciiDoc If you are new with it, see AsciiDoc Language Documentation.

If you want to test your changes, see Building Documentation.

Philosophy

  • 1 change = 1 patch

  • Update the documentation with the code.

  • Organize the AsciiDoc files into subdirectories.

  • Keep separate documentation for every different process to avoid confusion.

  • Do not assume that readers know everything you currently know.

  • Avoid jargon and acronyms, if you can.

  • Avoid multiple variations or spellings to refer to the same function, element, and so on.

  • Write short and useful documents. Cut out everything unnecessary, while also making a habit of continually improving every doc to suit your changing needs.

Document Layout

  • Document header: include your name and a revision line following the author line. Example:

    = Document Title
:description: Some words about the content.
Author Name <author@example.org>
v1.0, 2012-02-10
//empty line that ends the document header

  • Licensing: include license information after a document header. For example:

    // SPDX-FileCopyrightText: year / Name, surname / email address or the company name
// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0

  • Double space: the double space after the period is deliberate. Some people find it improves readability, and others do not like it, but the reason we use it in Spectrum documentation is that it allows text editors (Emacs) to differentiate between the ends of sentences and abbreviations (like "etc."), which means that you can make commands like "move to the next sentence" work accurately even if those abbreviations are used.

  • Character line limit:

    • Keep text hard-wrapped at 70-80 characters. (Most editors should be able to do this automatically.) This makes it easier to pick out specific parts in review, and also makes it easier to read in some editors. (It does not make a difference to the result as rendered in the web browser.)

    • Keep the text in the description attribute hard-wrapped as well. For more information, see the Document Metadata section of the Asciidoctor Docs.

  • Put one sentence on each line. This makes it easy to move content around, and also easy to spot (too) long sentences. For more information, see AsciiDoc Recommended Practices.

Structure

  • Use subheading to organize information.

  • One topic per article.

  • To make accents, use admonitions.

  • Use numbered lists for actions that happen in sequence.

  • Do not use parenthesis for additional information, make a separate sentence instead.

Language

Plain English

Plain language is a universal language that makes information clear and better to understand.

  • Short, sharp sentences.

  • Use simple tenses.

  • Write in an active voice.

  • Understandable language, fewer gerunds.

  • Do not contract the words: use cannot instead of can’t.

  • Write the full name when first mentioned with the acronym in brackets.

  • Use numerals for numbers.

  • Do not use Latin words. For example:

    • perform operations, etc. ⇒ perform operations, and so on

    • e.g. a Microsoft SQL Server ⇒ for example, a Microsoft SQL Server

    • via the system ⇒ through the system

Spelling

  • Use standard United States (U.S.) English. In cases where US spelling differs from UK spelling, use the US spelling. There is no need to fix one by replacing it with the other.

  • When you use filenames, URLs, and data parameters in examples, try to avoid words that are spelled differently by different groups of English speakers.

  • Use serial (Oxford) commas.