Style Guide

The present style guide aims at streamlining the authoring process. We would like to maintain a consistent style to guarantee a pleasant reading experience. If you haven't done it already, please read the Documentation Contributor FAQ before using this guide.

A style guide is meant to be used as a reference when there is a doubt about a style convention. Think of it as a set of recommendations to avoid time-consuming discussions about grammar, typography, and layout aspects.

It is not a novel that we expect you to read from A to Z. For instance, if you want to know how to format date and numbers, you can head immediately to the relevant section under Dates, times, and numbers.

In an ideal world, the reviewer is the person that must be in charge of enforcing the guidelines provided in the style guide.

We intend to reach people from different knowledge backgrounds and life experiences. Therefore, we kindly ask you to follow these rules:

Organization of the style guide

We are still at the beginning of our documentation journey. As of now, the style guide consists of three main components:

1. Layout and typography
2. Document structure
3. Wording and terminology

Feel free to suggest any additional points and/or sections you deem necessary.

Layout and typography

Follow these guidelines to organize the structure of your document:

Code Blocks

• Configuration files: Small configuration files should be enclosed in Markdown code blocks.
• Command line input:
  • If you include a command that is meant to be executed by an ordinary user, prepend the character $.
  • Likewise, if a command is meant to be executed by root / an administrator, prepend the character #.
• Command line output:
  • If the output is of direct relevance to the user, avoid screenshots. Use a Markdown code block instead.
  • If the output is too large, try trimming irrelevant lines first and explain what the reader should look out for.

Images and UI Descriptions

Screenshots and other images can heavily improve the quality of an article without much effort.

In our situation, screenshots generally help users find what they are looking for. They also use them to compare what they are seeing with what the article's author expects them to be seeing.

However, readers that cannot see images (e.g. users depending on screen reader software) should not be prevented from reading your article.

• Use text to describe instructions (i.e. where does the reader need to click). Do not exclusively rely on visual cues (i.e. arrows, icons) in screenshots.
• When possible, use text to describe what you expect the reader to see after following an instruction or a set of instructions.
• When using images, always use an adequate amount of alt text.

Headings

• Keep your headings short.
• Do not use periods (.) and colons (:) at the end of your headings.
• Avoid using consecutive headings without any content in between.
• Avoid using abbreviations in the headings. This particularly applies to lesser known abbreviations.
• Use sentence-style capitalization, i.e. capitalize only the first letter of the first word in the heading as well as words where capitalization is compulsory, such as proper nouns.
• Your headings must reflect the content of the text that follows.
• Begin your headings with the following parts of speech according to the typology of your content:

Unordered and ordered lists

By unordered lists, we mean bullet-style lists. Use unordered lists when the sequence is irrelevant, e.g.:

• The print() function
• The input() function
• The len() function

By ordered lists, we mean numbered lists. Use ordered lists to describe procedures that involve multiple sequential steps, e.g.:

1. Type the URL into your browser's address bar
2. Press the Enter button
3. Go to the Login section and click on “Forgot Password”

Maintain a consistent punctuation style in lists. Decide whether you will use “complete sentences” or “sentence fragments” in your list items. Add a period (.) at the end of each list item if you choose to use complete sentences. Do not add a period at the end of each item if you are only using sentence fragments.

Straight and curly quotes

Use curly quotes instead of straight quotes, e.g.:

Dates, times, and numbers

Please follow the conventions below to ensure a consistent format of dates, times, and numbers.

Dates and times

Use the following format for dates in running text: dd MMMM yyyy, e.g. 9 March 2022.

Use the following “short” format for dates outside the running text: dd.mm.yyyy, e.g. 9.3.2022.

Do not use leading zeros in dates, e.g.:

Use the 24-hour system. Do not use the 12-hour system with a.m. and p.m.

Do not use leading zeros to indicate time. Write full hours with zero minutes.

Numbers

Write out the numbers zero to nine in letters.

Use digits for all numbers above 9.

Use a combination of digits and letters when you have numbers that involve millions, billions, etc.

Hyphenation

Write “email” in lowercase characters without a hyphen. Do not use any other variant such as “e-mail” or “E-mail”, etc.

Use hyphens with compound adjectives and adverbs before nouns to eliminate any possible ambiguities, e.g.:

Do not use hyphens for adjectives and adverbs ending in -ly, e.g.

Document structure

If you write an excessively long article, your readers might get lost on the way. Break your article down in smaller articles for a better reading experience.

Avoid the excessive use of hyperlinks and cross-references within your document to prevent readers from being distracted.

Sentences and paragraphs

A standard paragraph consists of three to eight sentences. If a paragraph exceeds the maximum allowed number of sentences, reorganize the information to enhance readability.

Favor “self-contained information units” over interconnected information units. An information unit is called self-contained when it does not depend on other information units to convey meaning. Interconnected information units make an excessive use of pronouns and conjunctions such as “this”, “it”, “consequently”, “therefore”, etc.

Notes and warnings

Keep notes and warnings outside the body of your running text. Use admonition boxes, also known as callouts, to show said information.

The syntax is as follows:

{% admonition "type" "title [optional]" %}

Content

{% endadmonition %}

If no title is provided will the admonition box default to the type being used as title.
Note the gaps between the content and the start and end tag. These are required to allow markdown to be rendered.

The following admonition types are currently available:

Topic typology

Adopt one of the following approaches according to the typology of your content (cf. the difference between “conceptual”, “procedural”, and “reference” content under the section Headings):

Wording and terminology

• Use simple and easy-to-understand terms in your writing
• Avoid references to culture-specific examples that people from other countries or continents may not understand
• Do not coin terms, i.e. create new ones, if a term denoting the same concept already exists
• Explain terms if you think that some readers may either not understand them or misinterpret them
• Do not use double negatives, e.g.:

We use the standard American spelling conventions which are enforced by a spellchecker.

• Start names with an upper case letter (e.g. Git instead of git, Markdown instead of markdown)