The NEST documentation style guide

Why do we have a style guide?

This style guide was created to provide a single reference point for content creation in NEST. This helps ensure the NEST user-level documentation remains clear and consistent. The style choices we make here are meant to follow the major trends in technical writing for software.

Contribute to the docs

If you want to add or modify documentation, make sure to read through this guide before writing a contribution.

We have templates for Python example scripts and the PyNEST API docstrings.

You will also need to know how to build the documentation locally on your machine: See User-level documentation workflow.

For additional information, including the Git workflow and making a pull request see Contribute to NEST.

A few tips on writing documentation

  • Be concise: Use short words and sentences; avoid unnecessary modifiers.

  • Be consistent: Follow this style guide and relevant templates,

  • Be specific: Avoid vague language; clarity is key.

  • Focus your message: Start with what is most important, and keep text relevant within given section.

  • Write for your reader: Try to understand what your reader needs to know; include context to what you are saying. Remember that most NEST users are computational neuroscientists, including students, not software developers!

  • Provide examples: Show, do not tell; if you can use code snippets, screenshots, or figures to illustrate a point, do so!

  • Avoid terms like “simply”, “just”, or “easy”: Your knowledge does not always equal your readers. Do not make your reader feel bad because they “simply” did not understand something.

  • Write positively: Use positive language rather than negative language.

Remember that the primary purpose of the documentation is to provide information to NEST users who are looking for it.

The language we use

  • We follow spelling and grammar rules of American English.

  • The markup language we use is reStructuredText. This includes documentation blocks in files written in Python and C++.

  • We avoid slang or jargon that is unnecessary or could be confusing to readers.

We do, however, use terminology appropriate to NEST and neuroscience when specific and exact terms are needed, which is often. But explanations or references should be provided for clarity in introductory texts and the Glossary.

If you have further questions about style rules not addressed here, use the Microsoft style guide as a resource or ask on the mailing list.

How to phrase content in NEST

Voice

Voice is how we talk to people through writing. The voice encompasses substance, style, and tone.

Our voice is

  • empathetic: We write thinking of whom we are writing for and what their needs are.

  • relaxed: We write in a natural, conversational way rather than an authoritative way.

  • factual: We write in a neutral style avoiding irony, humor, or cultural references.

Use “you” to indicate the reader and “we” to indicate yourself (the writer and possibly the NEST team).

Active voice

  • Prefer the active voice, where the subject acts on object.

  • If the object needs emphasis rather than the subject, use passive voice. But ensure that you cannot improve the sentence by using the active voice.

Headings and subheadings

  • Headings and subheadings describe the purpose of the section.

  • Begin with a descriptive verb or begin with “How to …”

  • Use the verb stem and not the gerund (“ing”) form of the verb. Use “Add a model” instead of “Adding a model.”

  • Avoid section names like “Introduction” or “Part 1”.

  • One-word subheadings are acceptable, if the section is short and the meaning is clear.

  • Use sentence case for headings and subheadings, that is, begin with an uppercase letter but with all other words in lower case (except proper nouns).

Good examples:

Bad examples:

Create your first neural network

Start here

How to set up and configure MUSIC

MUSIC and NEST

Add a device to your network

Adding devices

Sentences and paragraphs

  • Avoid using “so” in sentences.

  • Try to keep sentences short, or break up long sentences with short ones.

  • Avoid lengthy paragraphs with more than 5 or 6 sentences. If writing multiple paragraphs, they should be broken up by example code, figures, or bullet lists.

  • Keep in mind that texts should be skimmable.

Pronouns

  • Use the pronouns “you” to indicate the reader and “we” to indicate NEST and its members.

  • Avoid the pronoun “I.”

  • Avoid gendered terms (e.g., use “police officer” instead of “policeman”).

  • Instead of “guys” or “girls” use inclusive language such as everyone, all, members, or folks.

  • “They” is an acceptable singular third person pronoun (see the dictionary definition here).

How to write specific content in NEST

Numbers

  • Numbers 0–9 should be spelled out, unless they are measurements or coordinates.

  • Numbers should be spelled out if they begin a sentence. In most cases, however, the numeral/ordinal format is preferred.

  • We use the period for the decimal point (57.45).

  • The thousand separator is the comma except when showing a code example.

    Example:

    We have over 5,000 connections. The number of connections is x = 5001.

  • Make sure you use the correct unit (e.g., millivolts for voltage) and the unit’s symbol (mV).

  • For additional mathematical notation, use the math role or directive.

Lists

  • Use the serial comma in lists.

  • Use numbered lists for step-by-step instructions only. Ensure that each step contains only one or two actions.

  • Use bullet lists if the number of items is extensive or each item is a long phrase or sentence.

  • If the text of a list forms a complete sentence, use proper punctuation and end with period.

  • If the text of a list forms an incomplete sentence, do not end with period.

  • If the entire bullet/numbered list belongs to a sentence, end each item with a comma and the second-last item with “, and”.

  • If the last item is the end of the sentence, end it with a period. Otherwise, use the punctuation required to correctly connect to the remainder of the sentence.

Abbreviations and acronyms

  • Spell out acronyms on first appearance on each page or article it appears, for example: Random number generator (RNG).

  • If the abbreviation/acronym is well known (e.g., HTML), you do not need to spell it out.

  • Use “e.g.,” and “i.e.,” only in parentheses and figure and table captions; otherwise, use “for example,” and “that is,”. Note the use of comma following the terms.

Contractions

  • Avoid contractions. For example, use “do not” instead of “don’t”.

Commas

  • Use the serial comma (apples, bananas, and grapes) for lists.

  • Use the comma as separator for thousands (37,000).

  • To join two sentences into one, you must use a conjunction (and, or, but) along with the comma, or use the semicolon.

Ampersand

  • Avoid the ampersand “&” and use “and” instead, unless the ampersand is part of a proper name (e.g., Ben & Jerry’s).

  • The ampersand is a special character and can be used, for example, to align multi-line equations.

Capitalization

  • Capitalize the first word of a heading, but use lower case for the rest.

  • Capitalize first word in bullet/numbered list.

  • Capitalize proper nouns and follow company policy in naming conventions. (e.g., macOS, LaTeX, Python, NumPy, NEST).

  • Capitalize the first word after a colon.

reStructuredText markup

reStructuredText is a plain text markup language and parser. It is the default language of the Sphinx documentation generator, which NEST uses for generating documentation.

reStructuredText uses directives, which are blocks of explicit markup used for math, images, code, admonitions, and much more. The syntax looks like this .. directive-name::. The directive content follows the directive name after a blank line and is indented relative to the directive start.

In addition to directives, reStructuredText has roles, which insert semantic markup into documents. Roles look like this :role-name:`content`.

We will only cover a few examples here. You can find more information at the following links:

Note

reStructuredText is sensitive to indentation and newlines.

  • Directives, headings, labels, and tables should be separated from other text by a newline, excluding directive options.

  • Directive options must be indented to the same level as the directive content.

  • Text in multiline content should stay aligned with the first line.

  • If the output format seems incorrect, double check the spaces and newlines of the text.

Code and code snippets

Code blocks are written by using the code-block directive.

Example syntax

.. code-block:: cpp

    int main()
    {
      std::cout << "Hello, World!";
      return 0;
    }

Code is rendered as

int main()
{
  std::cout << "Hello, World!";
  return 0;
}

For Python examples that show input and output, use the following syntax:

>>> input begins with 3, right-angled brackets
Output is directly below input without any brackets.
A blank line must end the example.

For in-text code use the role :code: or double backticks:

``cout << "Hello, World!`` or
:code:`cout << "Hello, World!"`

Math equations

The input language for mathematics is LaTeX markup. See Mathematics into Type for a guide to styling LaTeX math.

For equations that take a whole line (or more), use the math directive:

.. math::

    f(x) = \int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i x \xi} \, d\xi.

Output rendered as

\[f(x) = \int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i x \xi} \, d\xi.\]

If the equation runs over several lines you can use double backslashes \\ as a separator at the end of each line. You can also align lines in an equation by using the & where you want an equation aligned:

.. math::

     (a + b)^2  &=  (a + b)(a + b) \\
                &=  a^2 + 2ab + b^2

Rendered as

\[\begin{split}(a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2\end{split}\]

For in-text math, use the math role:

Now we can see :math:`x=1` for this example.

Rendered as

Now we can see \(x=1\) for this example.

Admonitions

Admonitions are directives that render as highlighted blocks to draw the reader’s attention to a particular point.

Use them sparingly.

Use the admonition

  • “See also” to reference internal or external links (only in cases where the reference should stand out),

  • “Note” to add additional information that the reader needs to be aware of,

  • “Warning” to indicate that something might go wrong without the provided information, and

  • “Danger” if the situation may cause severe, possibly irreversible, problems.

If you want a custom admonition, use:

.. admonition:: Custom label

   Here is some text

Rendered as

Custom label

Here is some text

References

There are two main ways to link to documents or sections of documents in reStructuredText.

The :doc: role can be used to reference whole documents. But it requires the relative path to the document. If a file is moved, then all references to the file need to be updated.

To avoid including paths, we try to use the :ref: role when possible.

Each reStructuredText file should include a reference label at the beginning of the file.

Sphinx can automatically link to these labels, so long as they are unique. You can also add labels anywhere within a document to label figures, subheadings, or arbitrary places in a file.

The :doc: role is used for auto-generated files such as the PyNEST examples and models, as well as some cases of intersphinx links, and Jupyter notebooks

Here is an example of the :doc: role:

:doc:`sample_doc`

In this case, the link text will be the title of the given document:

You can specify the text you want to use for the link by doing the following:

:doc:`custom label <sample_doc>`

This will be rendered as

The :ref: role requires a reference label that looks like this .. _type_ref-label:.

.. _sec_my-ref-label:

Section to cross-reference
--------------------------

Some content in this section.

The :ref: role for cross-referencing has the following syntax:

:ref:`sec_my-ref-label`

Rendered as

  • Each reference label must be unique in the documentation.

  • The label must begin with an underscore “_” for Sphinx to recognize it. But the reference to the label (i.e., :ref:`ref-label`) does not include the underscore.

  • Labels at the beginning of the document should be close to the filename or main heading of that document.

  • Use “sec_” (section), “fig_” (figure), “eq_” (equation), “tab_” (table), at the beginning of each reference label to denote the type of reference, within a document.

  • Separate the reference label from the text it is referencing with a newline.

  • To reference figures, equations, or arbitrary places in a file, you must include a custom label in the reference for it to work:

    :ref:`custom label <eq_my-arbitrary-place-label>`

Rendered as

reStructuredText text formatting

Underlines for headings

reStructuredText uses several types of underline markers for headings. It is important that the length of the underline is exactly as long as the words in the heading.

In general, we try to follow the pattern:

  • First heading: ===

  • Second heading: ---

  • Third heading: ~~~

  • Fourth heading: ^^^

“Double quotes”

We use double quotes for strings in code, for example, nest.Create("iaf_psc_alpha"). This applies to reStructuredText files as well as Python and C++ code. This rule is based on PEP 257, which (only) dictates the use of double quotes in triple quoted strings; for consistency, double quotes are used throughout the codebase.

Double or single quotes should not be used to emphasize important concepts in the text.

``Double backticks``

Use double backticks for all code and command related terms, such as function call examples, paths, variables, and parameters. In addition, meta and special characters (such as the ampersand &) should also be written in double backticks.

For example:

``nest.Create("iaf_psc_alpha")``

``/path/to/source/file.rst``

"The key ``rule`` in the connectivity specification dictionary ``conn_spec`` . . . "

**Strong emphasis** vs *emphasis*

  • Avoid using strong emphasis (boldface) in texts. If you want text to stand out use an appropriate admonition.

  • Use the plain emphasis (italics) to signify context differences within a text.

NumPy style docstrings

  • In PyNEST code, we follow most of the rules for NumPy style docstrings as explained in the NumPy style guide.

  • However, we use different formatting marks than what is stated in their guide. See section on double backticks.

  • If you are contributing to the PyNEST API, make sure you carefully read the NumPy guide, along with this one.

Bibliography style

The reStructuredText bibliography style is used throughout the documentation so that links are autogenerated and a consistent format is used.

For in-text citations, we use the reStructuredText numeric style [1]_.

Rendered as

The following example is based on Smith [1].

Sanders et al. [2] contains a technically detailed example.

Please ensure your reference follows the following guidelines.

  • Do not add formatting markup such as italics, bold, or underline.

  • Use a period after every section of bibliography.

  • Use et al. for references with more than five authors.

  • Put surname before first name for all authors.

  • Do not put commas after surname.

  • Use inital for first name of all authors.

  • Put year, in parentheses, after authors.

  • Write article titles in sentence case.

  • Write the full title of journal.

  • Insert a colon between volume and page-range.

  • Add issue in parentheses after volume (optional).

  • Include a linked DOI, if available.

Example of the reStructuredText syntax:

References
-----------

.. [1] Smith J. and Jones M (2009). Title of cool paper. Journal of
       Awesomeness. 3:7-29. <DOI>

.. [2] Sander M., et al (2011). Biology of the sauropod dinosaurs: The
       evolution of gigantism. Biological Reviews. 86(1):117-155.
       https://doi.org/10.1111/j.1469-185X.2010.00137.x

Rendered as