6.9.2

# Style Guide for Documentation

## File Layout

The documentation of an executable module comes as a pair of source files:

- A description XML file (.xml) giving command details, command-line and configuration parameters,

- A documentation reST text file (.rst) gives a more-detailed module description and examples.

Any other documentation, e.g. this style guide, tutorials, etc. only require the documentation reST text file.

The reST text file should follow the guidelines in this style guide.

The Contributing Documentation section details the documentation requirements for executables including the structure of description XML files.

## Documentation Syntax

A template for a typical application or module in reST is in `doc/templates/app.rst`. An introductory paragraph should describe the purpose of the executable. The introduction is followed be any additional information needed to understand the command, introduced with one or more headings. Add information about testing and examples into their own sections.

### General principles

- If possible, keep line lengths under 80 characters.

- It eases later editing if sentences in the raw RST start on a new line, even though they will flow together in the finished document.

- It is helpful if long text objects such as HTML link text each appear on their own line.

### Section and headings

Module description files do not require top-level headings, as the build script will take this text and assemble it with other description information in the appropriate part of the documentation.

While RST doesn’t care too much about what syntax is used for headings, it is best to stick to one style consistently. Thus, you will generally need only two levels of headings but you can add more.

Level | Mark up beneath heading text
--- | ---
1 | ‘ ==== ‘
2 | “ —- “
3 | ‘ ~~~~ ‘
4 | ‘ ^^^^ ‘

Use Title Case for headings within a section, and make only the first letter uppercase for subheadings. Higher levels, marked up with asterisks, are used for sections of the documentation.

Example:

    Level 1 Title
    =============

    Some text.

    Level 2 title
    -------------

    Some text

Parts such as Examples are marked in bold.

However notes and figures should use the appropriate RST directive, and don’t require their own headings.

- One blank line below headings is enough.

- Two lines above are often used, and this looks better than one.

### Lists

Use numbered or unnumbered lists at several levels.

- Start list items at the first level with a capital letter. End them with a full stop.

- Use lower-case letters for all other levels. End them with a full stop.

    #. Item 1.
    #. Item 2.
       * subitem 1.
         #. subsubitem 1.
         #. subsubitem 1.
       * subitem 2.

Result:

1. Item 1.

2. Item 2.

   - subitem 1.

     1. subsubitem 1.

     2. subsubitem 2.

   - subitem 2.

### Other markup tools and conventions

- Code fragments: Use the reST code-block syntax for code fragments, with flavors like “c”, “python”, “sh”, “bash”, “properties´” or “xml” as appropriate:

      .. code-block:: sh

         #!/bin/bash
         echo $SEISCOMP_ROOT

  Result:

      #!/bin/bash
      echo $SEISCOMP_ROOT

- Configuration parameters: Configuration values have a special syntax. Use the ‘:confval:’ indicator for referencing a module configuration parameter:

      :confval:`logging.level`

  Using this tag allows a link to be made within the documentation of that module to the given configuration of the same module. The parameter must be defined in the description XML file of the module.

- Command-line options: Command-line options have a special syntax. Use the ‘:option:’ indicator for referencing an option:

      :option:`--help`

  The option must be defined in the description XML file of the module.

- Configuration files: Use the reST ‘:file:’ indicator to refer to files such as configuration files:

      :file:`$SEISCOMP_ROOT/etc/scautopick.cfg`

  Result: `$SEISCOMP_ROOT/etc/scautopick.cfg`

- Programs: Use the reST ‘:program:’ indicator for SeisComP programs:

      :program:`scautopick`

  Result: scautopick

- References: Use the reST ‘:ref:’ indicator for cross referencing SeisComP module documentation pages:

      :ref:`scautopick`

  Result: scautopick

- Glossary: Use the reST ‘:term:’ indicator for referencing terms in the SeisComP Glossary:

      :term:`magnitude`

  Result: magnitude

### Internal links

Create links to sections and subsections within and to figures the text which can be referenced. Use unique link names, e.g. including the upper-level section name or the module name. Use appropriate short names to fit within the texts.

Link within this documentation to the section on headings:

    .. _documentation_style_guide_headings:

Reference:

    :ref:`short name <documentation_style_guide_headings>`

Result: short name

### External links and references

Preferably you do not show full citations or URLs for literature or external web sites within the text but make references which are listed in the section References. Procedure:

1. Add publications, external URLs, etc. as complete citation entries to the reference list `doc/base/references.bib` in the base SeisComP repository on Github.

2. Cite documents within the RST file using the cite directive

       :cite:p:`seiscomp`
       :cite:t:`seiscomp`

   which results in [67] and Helmholtz-Centre Potsdam - GFZ German Research Centre for Geosciences and gempa GmbH [67] within the documentation HTML text.

If you really cannot avoid URLs in RST files, then you may link them to some text like

    `SeisComP forum <https://forum.seiscomp.de/>`_

resulting in SeisComP forum.

Alternatively you may generate reference in a Reference sections as

    References
    ==========

    .. target-notes::

    .. _`discussion` : https://english.stackexchange.com/questions/65630/you-should-be-well-organised-or-you-should-be-well-organised

and then cite it within the text as

    `discussion`_

which results in discussion [1].

### Text boxes

You may emphasize information within the text as text boxes to stand out at different levels. Make sensible use of it!

- Hints

      .. hint::

         This adds a useful hint.

  Result:

  Hint

  This adds a useful hint.

- Notes

      .. note::

         This adds an extra note.

  Result:

  Note

  This adds an extra note.

- Alerts

      .. caution::

         This adds a heads-up alert.

  Result:

  Caution

  This adds a heads-up alert.

- Warnings

      .. warning::

         This adds an important warning.

  Result:

  Warning

  This adds an important warning.

## English Language

- SeisComP (capital P), not SeisComP 3 or SC3.

- SeisComP module names are proper nouns, even though written with lower case. Thus they do not need an article.

  - Correct: “Although scmaster receives a message”

  - Incorrect: “Although the scmaster receives a message…”

A sentence may begin with a lower case module name e.g. “scmaster has five modes…” avoiding this: “The scmaster module has…”

- Word separation:

  - Separate words: base class, wave number, time span

  - One word: aftershock, foreshock, and mainshock too, bandpass, eigenperiod etc., metadata, standalone, username, workflow, waveform

  - Difficult: high-pass filter; command line; command-line parameter

- Hyphenation for compound adjectives: yes, before a noun; after verb to be is harder. See the discussion [1], e.g.:

  - Use command-line parameters

  - Type on the command line

- Spelling:

  Use American English:

  - With ‘z’: digitizer, realize, visualize, synchronize, behavior, color.

  - With ‘s’: license.

  - Center, data center.

- Case:

  - SEED, miniSEED (miniSEED in libmseed - The miniSEED data format library [32], or MiniSEED, but Mini-SEED appears in Appendix G of the SEED Reference Manual [31].)

  - Ctrl+S for ‘control’ key plus ‘s’.

  - MySQL, PostgreSQL, MariaDB

- Abbreviations:

  - e.g., i.e.

  - STA, LTA, STA/LTA detector

  - TAR file

## Adding Images

### Code implementation

- Add images with fixed width.

- Add image captions.

- Store images in a separate directory of below the directory where the documentation is kept.

Example for an image which can be enlarge by mouse click:

    .. figure::  media/image.png
       :alt: image one
       :width: 10cm
       :align: center

       Image one.

Example for images in two columns which cannot be enlarged. Up to 4 columns are possible. Compare with the concept section on configuration:

    .. raw:: html

    <div class="two column layout">

    .. figure:: ../media/scconfig_no_bindings.png
       :alt: scconfig: bindings configurations

       scconfig modules panel indicating that no bindings can be configured.

     .. figure:: ../media/scconfig_has_bindings.png
        :alt: scconfig: no bindings configurations

        scconfig modules panel indicating that bindings can be configured.

     .. raw:: html

     </div>

### Image style and format

- Images shall be informative.

- Images must not have any offensive or inappropriate content.

- Use PNG format.

- Make the important image details readable at the normal image size without enlargement.

- Images shall be optimized for file size.

- Images should have a frame, e.g. a window frame.

- Avoid private information on images.

- Do not show desktop background unless required.

- Images from SeisComP GUIs can be screenshots.

- Do not create screenshots from applications started remotely with X-forwarding. X-forwarding may distort the application features.

## References

[1] (1,2)

https://english.stackexchange.com/questions/65630/you-should-be-well-organised-or-you-should-be-well-organised