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¶

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.

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]

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¶

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.

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

Spelling¶

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¶

Line breaks¶

Start each sentence on a new line.

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:

• Before and/or after a Markdown link
• Before an opening HTML tag (or Markdown equivalent) or after a closing tag
• After punctuation that begins an independent clause
• At another natural place

Also add a line break somewhere if you think it’s helpful. In particular, consider around a long Markdown link, or before items of an inline list. For example:

You must additionally follow the
[Advanced Selection Criteria](https://github.com/organization/selection/criteria.md).
That includes Criteria 3–6:
(3) diagnostic equivalence;
(4) generational set–set parity;
(5) non-availability of identity; and
(6) interdimensional periodicity.

Text styles and semantics¶

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

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.

Alternative: <em>:

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

Alternative: <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¶

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 –.

Exceptions:

Use hexadecimal entity references for

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

Unicode characters¶

Use the correct Unicode characters for punctuation.

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¶

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. Some fonts lack glyphs for musical neutral and musical rest.

Quotations¶

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.

Then run

```
ps -a -x
```

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¶

• A period (.) as the decimal separator
• A narrow no break space, (NNBSP / U+002D /  ) 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}. With LuaLaTeX, you can use proper Unicode mathematical glyphs along with siunitx, using fontspec, \unimathsetup and \sisetup as done in fontworthy.sty.

Uncertainty measurements¶

State whether a value means standard error or standard deviation. Do not write 5.0 ±0.1 – that’s ambiguous. Use the abbreviations standard error (SE), standard deviation (SD), and confidence interval (CI). Use one of these formats:

• Standard error: 7.65 ±1.2 (SE)
• Standard deviation: 7.65 ±0.54 (SD)
• Confidence interval: 7.65 (4.0–12.5, 95% CI)
• SE/SD with units: (7.65 ±0.54) J·m⁻² (SD)
• CI with units: 7.65 (4.0–12.5, 95% CI) J·m⁻²
• CI with units (alt): 7.65 J·m⁻² (4.0–12.5, 95% CI)

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.

Closing tags¶

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

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

Always include these elements.

Formal grammars¶

Grammars may be specified in any well-defined form. The IETF’s ABNF (see RFC 5234, The meta-grammar defined in the XML spec, and regex-BNF are recommended.

With ABNF, do not use the incremental alternatives notation (=/), which modifies an already-defined rule, complicating reading. Avoid the core rules CHAR, LWSP, CTL, VCHAR, and WSP.