Skip to content

Documentation conventions

Summary points / highlights

These guidelines are aggressive and lengthy (more than originally intended). Skip the details gloss over the details. Here are the important points.

Filenames:

  • Use lowercase-kebab-case, limiting characters to [a-z0-9-].
  • Use LICENSE.txt over LICENSE and config.yaml over config.yml.

Language:

  • Keep language simple, and be explicit.
  • Sometimes an example is sufficient.

Markdown:

  • Start a new line for every sentence (it helps with diffs).
  • Limit lines to 120 characters, breaking before puncutation where possible.
  • Use **bold** for emphasis, _italics_ as the <i> element, and <b></b> for non-emphasized but bold text; e.g. <b>Score:</b> 12.5.

Comments:

  • Forgo comments that are superfluous or included out of habit or convention.

Filenames

Tip

This section can apply to naming of URI nodes, database IDs, and similar constructs. These are general guidelines: Alternatives should be used in some situations. For example, if camelCase is used in your JSON Schema, use camelCase for schema document filenames.

Rationale

The official YAML extension is .yaml. Moreover, the IANA media types are application/yaml, text/html, and image/jpeg. .yml, .htm, and .jpg are relics of DOS. Extensions are required because provide useful information; ommitting them can cause confusion. For example, a file named info could be a plain-text info document or a shell script that writes the info. Instead, write it as info.txt or info.sh.

Prefer kebab-case (e.g. full-document.pdf), treating - as a space. Restrict to -, ., [a-z], and [0-9], unless there is a compelling reason otherwise. If necessary, --, +, and ~ can be used as specialized word separators. For example, + could denote join authorship in mary-johnson+kerri-swanson-document.pdf.

Always use one or more filename extensions, except for executable files; e.g. LICENSE.txt or LICENSE.md, not LICENSE. Where possible, use .yaml for YAML, .html for HTML, and .jpeg for JPEG. In particular, do not use .yml, .htm, .jpg, or .jfif.

Comments

Comments must be maintained like all other elements of code. Avoid unnecessary comments, such as those added out of habit or ritual. Forgo comments that are obvious or otherwise unhelpful.

Example
from typing import Self, TypeVar


class SpecialCache:
    """
    Soft cache supporting the Foobar backend.
    Uses a Least Recently Used (LRU) policy with an expiration duration.
    """

    def get_cache_item(self: Self, key: str) -> T:
        # (1)!
        """
        Gets the cache item corresponding to key `key`.

        Arguments:
            key: A string-valued key

        Returns:
            The value for the key `key`
        """
        return self._items[key]
  1. This docstring serves no function.
from typing import Self, TypeVar


class SpecialCache:
    """
    Soft cache supporting the Foobar backend.
    Uses a Least Recently Used (LRU) policy with an optional expiration duration.
    """

    def get_cache_item(self: Self, key: str) -> T:
        return self._items[key]

Language and grammar

Tip

Apply these guidelines to both comments and documentation.

See Google’s documentation style guide for additional guidelines.

Style

Remove text that is repetitive or superfluous. Be direct. Use examples, diagrams, formal grammars, pseudocode, and mathematical expressions. Write English descriptions for diagrams and any other elements that are be inaccessible to screen readers.

Keep language accessible: Introduce or explain jargon, favor simpler words, and replace idioms with literal phrasing. Do not rely on mutual agreement about subtle differences between similar words. For example, do not use both significant and substantial. To distinguish a very significant finding from a significant one, write very significant. Be explicit. Use singular they and other gender-neutral terms, and use inclusive language. Substitute long phrases with shorter ones.

Examples
❌ Avoid ✅ Preferred
utilize use
due to the fact that because
a great number of many
is able to can
needless to say (omit)
it is important to note that importantly,

Great documentation should not win poetry awards. Keep things simple and direct.

Spelling

Rationale

American English is the most widespread dialect, and it generally has more phonetic and shorter spellings.

Use American English spelling.

Grammar and punctuation

Use 1 space between sentences.

Use sentence case for titles and table headers (e.g. This is a title). Capitalize the first word after a colon only if it begins a complete sentence; do not capitalize the first word after a semicolon.

Terminology

Avoid the terms URL and URN; just use URI instead.

Markdown

Tip

Where applicable, apply these guidelines to other documentation, not just Markdown.

Line breaks

Rationale

Keeping each sentence on its own line dramatically improves diffs.

Start a new line for each sentence.

If needed to prevent a line from exceeding 120 characters, add line breaks elsewhere. Look for one of these places to add a line break, in order:

  1. before a Markdown link
  2. After a colon, semicolon, or dash ()
  3. After a comma that begins an independent clause
  4. After any other punctuation
  5. Before an opening HTML tag (or Markdown equivalent) or after a closing tag
  6. At any other natural place

Notes:

  • Add line breaks wherever you think they are helpful for items 1–4; e.g. before each item of an inline list (i.e. before (1)).
  • You may leave a series of very short sentences on one line; e.g. Be smart. Be fast. Be good..

Text styles and semantics

Semantic HTML elements

Some semantic HTML elements are result in identical styles (in most browsers). This table summarizes how to use them in HTML and in Markdown.

element style usages equivalent Markdown
em italic emphasis; stress <em>text</em> (prefer bold)

| i | italic | technical terms; foreign text; more | _text_ | | var | italic | terms being defined | _term_ or <dfn>term</dfn> | | var | italic | variables | $var$ | | strong | bold | strong emphasis | **text** | | b | bold | keywords, miscellaneous | <b>text</b> | | code | monospace | source code | `code` | | samp | monospace | sample output | `code` | | kbd | monospace | keyboard keys | <kdb>keys</kbd> |

Italics

Take _/_ (and */*) as semantically equivalent to the <i> element.

Uses of _/_:

  • Foreign words, technical terms, etc.
  • Non-semantic references (words/phrases themselves, not their meanings).
  • Single quotation marks (/) are also acceptable.

Non-uses of _/_:

  • Ubiquitous foreign phrases like in vivo, in sitro, in silico, and et al.
  • Emphasis (i.e. importance).
  • Stress (e.g. to distinguish <<I>> will go there and I will go <<there>>.). Instead, consider making the exact meaning explicit by rephrasing; e.g. I (specifically) will go there. Keep in mind that screen readers may not announce the italicization.

<em>:

Italics are occasionally helpful for emphasis or stress. If needed, use an explicit <em>; e.g. I will go <em>there</em>.

<dfn> Using the dfn element in Markdown is good practice. _/_ is an acceptable substitute.

Bold

Use **/** bold for emphasis. Take **/** as semantically equivalent to the <strong> element.

Use the <b> element explicitly rather than **/** for text that should be bold but not emphasized – i.e. semantically distinct from the surrounding text. For example, you might write <b>Score:</b> 55.3%.

Code and math

Tip

With the Material for mkdocs “Smarty” plugin, you can use ++/++ instead of <kdb>/<kdb>; e.g. ++ctrl+alt+del++.

Use backticks for code, <kbd>/</kdb> for keyboard keys, and LaTeX ($/$) for variables and mathematical expressions. To describe menu navigation, use without markup; e.g. File ➤ Export ➤ Export as Text.

Encoding

Write most non-ASCII characters as-is, not with entity references. For example, write an en dash as , not &#x2013;.

Exceptions:

Use hexadecimal entity references for

  • non-space whitespace characters; and (such as no break space, &nbsp;); and
  • punctuation that is highly likely to confuse anyone reading the source code (such as soft hyphen, &#x00ad;); and
  • characters that must be escaped for technical reasons

Unicode characters

Tip

With the Material for mkdocs “Smarty” plugin, you can use use ' and " for quotation marks, -- for en dashes, --- for em dashes, and ... for ellipses.

Use the correct Unicode characters for punctuation.

Examples
  • for apostrophes
  • , , , and for quotation marks
  • (en dash) for numerical ranges (e.g. 5–10)
  • (em dash) to separate a blockquote and its source
  • (figure dash) in numerical formatting
  • (ellipses)
  • (minus sign)
  • µ (micro sign)

However, use regular hyphen-minus (U+002D) for hyphens, not hyphen (U+2010).

Punctuation (prescriptive grammar)

Use an en dash surrounded by spaces () to mark breaks in thoughts, not an em dash. For example:

An en dash – in contrast to an em dash – should be used here.

For i.e. and e.g., skip the comma (British English) and normally introduce with ;,. For example: say something nice; e.g. “nice boots”..

Abbreviations

Use the <abbr> HTML tag with the title attribute in Markdown. For the first appearance, consider writing it out in this format: Public Library of Science (PLOS). Omit periods (.) for initialisms; e.g. USA, not U.S.A..

† Note that the correct abbreviation for PLOS is PLOS, not PLoS.

Admonitions

Material for mkdocs supports admonitions. Use them for content that either:

  • is offset/apart/distinct from the surrounding text (i.e. like the <aside> element);
  • describes the content itself; or
  • content that many readers should skip (do this sparingly).

Footnotes

Rationale

These symbols are easily recognized as indicating footnotes, whereas superscript numbers could be confused with reference numbers or even exponents in some places. They are more accessible than superscript symbols for people who are vision-impaired. (The pilcrow is excluded because it is too thick/prominent.)

Unless the Markdown flavor handles footnotes in another way, follow this format:

This statement is false.

<small>† Note that this is a contradictory statement.</small>

Use these symbols, in order: (dagger), (double dagger), § (section mark), (paragraph mark), (musical sharp), 𝄮 (musical neutral), 𝄽 (musical rest). Other schemes, such as superscript numbers or letters, may sometimes be acceptable alternatives.

Quotations

Rationale

This preserves the semantic difference between punctuation inside and outside of quotations. This rule is always followed when using code in backticks, anyway. A colon is a visual signal that the prose goes with its following code block, reducing refactoring mistakes.

Place punctuation outside of quotation marks (British-style rules). For example:

Also write ‘hard’, ‘difficult’, or ‘strenuous’.

Introduce code blocks with punctuation only where semantically valid. If it is semantically valid, use a colon rather than a comma. In blockquotes, use _— author_ (with an em dash) to cite the source.

Examples

In the following block, use then run, not then run:.

Then run

```
ps -a -x
```

Here, a colon is appropriate:

Mark Twain also said:

> When in doubt‚ tell the truth.
> This is a blockquote, which is ordinarily introduced by punctuation.
> For clarity, we introduce such blockquotes with colons.
> _— Mark Twain_

Inline lists (enumerations)

For inline lists, follow this format:

(1) Use (1), (a), or (i); (2) use commas or semicolons; (3) start a line for each item; (4) include and, or, or nor at the end of the line; and (5) end the last line with . (or other appropriate punctuation).

Quantities

Rationale

This is the format that IEEE recommends.

  • A period (.) as the decimal marker
  • A narrow no break space, (NNBSP / U+002D / &#x202f;) as the thousands separator
  • A full space () to separate magnitude and units

✅ Preferred 1 024.222 222 µm (result: 1 024.222 222 µm)

🟨 Acceptable 1024.222222 µm (result: 1024.222222 µm)

❌ Not acceptable 1,024.222222 µm or 1.024,222222 µm

Preferably, write units using decimal dot (·, U22C5).

✅ Preferred 5.4 kg·m²·s⁻² (result: 5.4 kg·m²·s⁻²)

🟨 Acceptable 5.4 kg m^2 / s^2 (result: 5.4 kg m^2 / s^2)

❌ Not acceptable 5.4 kg m^2 /s^2 (result: 5.4 kg m^2 / s^2)

Note: You can use inline LaTeX ($/$) to format dimensioned values instead. E.g., 5.4 kg m^2 s^{-2}. Preferably, use siunitx with mode=match,reset-math-version=false,reset-text-family=false.

Uncertainty measurements

State whether the values refer to standard error or standard deviation.

Abbreviations:

  • SE: standard error
  • SD: standard deviation

Examples:

  • 7.65 (4.0–12.5, 95% confidence interval)

  • 7.65 ±1.2 (SE)

❌ Do not just write the uncertainty without explanation, e.g. 5.0 ±0.1 – it is ambiguous.

✅ Do describe how the uncertainty was estimated (i.e. a statistical test).

Dates and times

Use RFC 3339. For example: 2023-11-02T14:55:00-08:00. Note that the UTC offset is written with a hyphen, not a minus sign. If a timezone is needed, use a recognized IANA timezone such as America/Los_Angeles, and set it in square brackets. The UTC offset must still be included. For example: 2023-11-02T14:55:00 -08:00 [America/Los_Angeles].

Durations and intervals

For durations, use, e.g., 8.3 s. hr, min, and sec/s are acceptable abbreviations, whereas M for minute is not. (Avoid ISO 8601 durations (e.g. PT45M55S) in documentation.)

Paths and filesystem trees

Always use / as a path separator in documentation, and denote directories with a trailing /.

For filesystem trees, use Unicode box-drawing characters. Refer to the research projects guide for an example.

Accessibility

Use descriptive titles for link titles.

Click [here](documentation.md) for conding conventions.

Refer to the [documentation conventions](documentation.md).

HTML

Follow the applicable guidelines from the Markdown section.

Attribute values

Use kebab-case for id and name values and for data keys and values.

Skip the type attribute for scripts and stylesheets. Instead, use <link rel="stylesheet" href="..." /> for stylesheets and <script src="..." /> for scripts.

Accessibility

Use the alt attribute for media elements, including <img>, <video>, <audio>, and <canvas>.

Formatting

Use Prettier with default options except for line length, which must be 120.

Note

Prettier wraps tags in way that looks strange at first. It does that to avoid adding extra whitespace.

Closing tags

Rationale

Requiring closing tags (and trailing slashes, which Prettier will add) improves readability and simplifies parsing.

Always close tags. For example, use <p>The end.</p>, not <p>The end..

<html>, <head>, and <body> elements

Rationale

The rules for ommitting <html>, <head>, and <body> are complex and better ignored.

Always include these elements.

Formal grammars

Grammars may be specified in any well-defined form. ABNF (see RFC5234), XML’s custom meta-grammar, and regex-BNF are recommended.

Rationale

=/ modifies an already-defined rule, which complicates reading. LWSP is commonly understood to be problematic.

With ABNF, do not use the incremental alternatives notation (=/), and avoid the core rules CHAR, LWSP, CTL, VCHAR, and WSP.