Writing and building documentation#

The documentation is written using reStructuredText language and is built with sphinx-build through a tox environment.

Style guide#

Follow these guidelines when writing the documentation.

Tense and voice#

For reference and general task-based docs use the “imperative mood”. These docs should be straightforward and conventional. For example:

To create a user, run:

.. code-block:: sql

    CREATE USER my_user;

For tutorials, the docs can be more casual and conversational but must also be straightforward and clear. For example:

In this lab, start with a fresh cluster. Make sure to stop and clean up the cluster
from the previous labs.

Future and conditional tenses#

Avoid future tense (will) and conditional tenses (would, could, should). These tenses lack precision and can create passive voice.

Use future tense when an action occurs in the future, for example:

This feature will be removed in a future release.

While present tense is strongly preferred, future tense can be useful and accurate in an “if/then” phrase. For example, it’s okay to write:

If you perform this action, another action will occur.

The conditional tense is okay only if you explain the conditions and any action to take. For example, use:

A message should appear. If it doesn't, restart the server.

Person#

Use second person (you) when referring to the user. Don’t use “the user” which is third person.

Use first person plural (we) to refer to the authors of the docs. For example, use:

We recommend that you restart your server.

Instead of:

Developers recommend that you restart your server.

However, don’t use first person plural when talking about how the software works or in an example. For example, use:

Next, Barman processes the instruction.

Instead of:

Next, we process the instruction.

Line length#

When possible do not overflow 88 characters per line in the source files. In general, exceptions for this rule are links.

Sentence length#

Avoid writing sentences with more than 26 words. Long sentences tend to make the content complicated.

Contractions#

In keeping with the casual and friendly tone, use contractions. However, use common contractions (isn’t, can’t, don’t). Don’t use contractions that are unclear or difficult to pronounce (there’ll).

Numbers#

Spell out numbers zero through nine. Use digits for numbers 10 and greater. Spell out any number that starts a sentence. For this reason, avoid starting a sentence with a long or complex number.

Dates#

When specifying dates for human readability, use the DD mmm YYYY format with a short month name in English. Where the date is being used in a column in a table, use a leading 0 on the day of month for easier alignment, for example, 01 Jan 2024.

When specifying dates as solely numbers, use ISO8601 format; YYYY/MM/DD. This is the internationally accepted, disambiguous format. Use it where you may expect the date to be read by automated systems.

Capitalization#

Capitalization rules:

  • Use sentence-case for headings (including column headings in tables).

  • Capitalize the first letter in each list item except for function and command names that are naturally lower case.

  • Capitalize link labels to match the case of the topic you’re linking to.

  • Capitalize proper nouns and match the case of UI features.

  • Don’t capitalize the words that make up an initialization unless they’re part of proper noun. For example, single sign-on is not a proper noun even though it’s usually written as the initialism SSO.

Punctuation#

Punctuation rules:

  • Avoid semicolons. Instead, use two sentences.

  • Don’t join related sentences using a comma. This syntax is incorrect.

  • Don’t end headings with a period or colon.

  • Use periods at the end of list items that are a sentence or that complete a sentence. If one item in a list uses a period, use a period for all the items in that list.

  • Use the Oxford (AKA serial) comma.

“This” without a noun#

Avoid using “this” without a noun following. Doing so can lead to ambiguity. For example, use:

This error happens when…

Instead of:

This happens when...

Directing users up and down through a topic#

Don’t use words like “above” and “below” to refer to previous and following sections. Link to the section instead or use “earlier” or “later”.

It also isn’t necessary to use the words “the following” to refer to list items. These words are empty. So, for example, use:

The color palette includes:

Instead of:

The palette includes the following colors:

Bold (text)#

Use for UI elements. For example:

The output of ``barman show-backup`` includes:

* **Backup Size**: the size of the backup.
* **Estimated Cluster Size**: the estimated size of the cluster once the backup is
  restored.

Also for roles and users. For example:

Run as **root**:

.. code-block:: bash

    dnf install barman

Courier (AKA inline code or monospace text)#

Use for parameters, commands, text in configuration files, file paths, packages and utility names. For example:

If you need to type the ``ls`` or ``dd`` command, add a setting to a
``configuration=file`` or just refer to ``/etc/passwd``, then this is the font
treatment to use.

Code blocks#

Use to provide code or configuration samples.

Example for code sample:

Execute this query:

.. code-block:: sql

    SELECT *
    FROM pg_stat_activity;

Example for configuration sample:

Create the file ``/etc/barman.conf`` with:

.. code-block:: ini

    [barman]
    ; System user
    barman_user = barman

    ; Directory of configuration files. Place your sections in separate files with
    ; .conf extension
    ; For example place the 'main' server section in /etc/barman.d/main.conf
    configuration_files_directory = /etc/barman.d

Italics (text)#

Use for book titles. For example:

We recommend you read *PostgreSQL 16 Administration Cookbook*.

Admonitions (notes, warnings, hints, etc.)#

When applicable use admonitions.

For multiple, consecutive admonitions, use separate admonitions.

Tables#

Use tables to display structured information in an easy-to-read format.

Lists#

Use lists to display information in items:

  • Numbered (ordered): Use to list information that must appear in order, like tutorial steps.

  • Bulleted (unordered): Use to list related information in an easy-to-read way.

Use period at the end of each list item.

Images#

Use images to clarify a topic, but use them only as needed.

Images are put inside the folder docs/images.

Cross-reference labels standard#

When creating cross-reference labels in Sphinx, please follow these guidelines to ensure consistency and clarity:

  1. Use Hyphens: Separate words in labels with a hyphen. For example:

.. _backup-overview:

2. Hierarchical Prepending: For each .rst file, prepend labels with the higher-level section label, followed by any intermediate sub-section labels. This way, the full hierarchy is represented in the label.

For example, a file called backup.rst can have the following label:

.. _backup:

Then, any subsequent labels in this file should start with backup-. For a sub-section labeled Overview the label would be _backup-overview:. For another sub-section in Overview the label would be like:

.. _backup-overview-other-section-under-overview:

Handling Included Files#

If your .rst file uses the .. include:: directive, evaluate whether the included files are closely related to the parent document:

  • Related Example: In a file commands.rst with the label:

    .. _commands:

    if you include another file, like commands/backup.rst, which is related, you would label the latter as:

    .. _commands-backup:

  • Independent Example: If the included section is not directly related, you may treat it as an independent section, without the hierarchical label prepending.

Purpose of This Standard#

Following this labeling standard helps us:

  • Easily trace the source of cross-references.

  • Avoid label duplication.

  • Simplify navigation for developers and end-users.

By adhering to these guidelines, we can create clear and maintainable documentation that enhances usability and understanding.

Building the documentation#

You can build the documentation in three different formats:

The documentation is built through a tox environment named docs.

HTML documentation#

To build the HTML documentation, run:

tox -e docs -- html

To view the HTML documentation, open the file docs/_build/html/index.html using your web browser.

PDF documentation#

To build the PDF documentation, run:

tox -e docs -- latexpdf

To view the PDF documentation, open the file docs/_build/latex/Barman.pdf using your PDF reader.

Linux man page#

To build the Linux man page, run:

tox -e docs -- man

To view the Linux man page, run:

man docs/_build/man/barman.1