Skip to content

Content Rules

George Bernard Shaw

The golden rule is that there are no golden rules.

Motivation and Rationale

This page holds rules regarding the layout, content, and writing of this documentation. The goals are to provide a comprehensive, consistent, up-to-date and well-written documentation that is pure joy to read and use. It shall help to find answers and provide knowledge instead of being the bottleneck and a great annoyance. Therefore, we set up some rules which are outlined in the following.

Tip

Following these rules when contributing speeds up the review process. Furthermore, your changes will not be blocked by the automatic checks implemented in the CI pipeline.

Responsibility and License

This documentation and the repository have two licenses (cf. Legal Notice):

  • All documentation is licensed under CC BY 4.0.
  • All software components are licensed under MIT license.

These licenses also apply to your contributions.

Note

If you contribute, you are fully and solely responsible for the content you create and have to ensure that you have the right to create it under the laws which apply.

If you are in doubt, please contact us either via GitLab Issue or via Email.

Quick Overview

Detailed Overview

Writing Style

  • Assume that a future reader is eager to start typing commands. Thus, encourage the reader by addressing him/her directly:
    • Example: Use "You can/should ..." instead of "Users can/should ..."
    • Example: Use "Your contribution is highly welcome" instead of "Contributions from user-side are highly welcome"
  • Be brief! Provide the main idea/commands first, and special cases later. If it is not necessary to know how a special piece of software works, don't explain it.
  • Provide the often-used commands first.
  • Use active over passive voice
    • Write with confidence. This confidence should be reflected in the documentation so that the readers trust and follow it.
    • Example: "We recommend something" instead of "Something is recommended."
  • Capitalize headings, e.g. Exclusive Reservation of Hardware
  • Give keywords in link texts, e.g. Code Blocks is more descriptive than this subsection
  • Avoid using tabs both in markdown files and in mkdocs.yaml. Type spaces instead.

Pages Structure and New Page

The documentation and pages structure is defined in the configuration file mkdocs.yml:

nav:
  - Home: index.md
  - Application for Login and Resources:
    - Overview: application/overview.md
    - Terms of Use: application/terms_of_use.md
    - Request for Resources: application/request_for_resources.md
    - Project Request Form: application/project_request_form.md
    - Project Management: application/project_management.md
    - Acknowledgement: application/acknowledgement.md
  - Access to ZIH Systems:
    - Overview: access/overview.md
  [...]

Follow these two steps to add a new page to the documentation:

  1. Create a new Markdown file under docs/subdir/file_name.md and put the documentation inside. The sub-directory structure represents different topics of the documentation. Try to fit the contribution into the existing structure. The file name should reflect the title of the documentation page, i. e. shortened_page_heading.md.
  2. Add subdir/file_name.md to the configuration file mkdocs.yml by updating the navigation section. Yes, the order of files is crucial and defines the structure of the content. Thus, carefully consider the right spot and section for the new page.

Make sure that the new page is not floating, i.e., it can be reached directly from the documentation structure.

Markdown

All documentation is written in Markdown. Please keep things simple, i.e., avoid using fancy Markdown dialects.

Brief How-To on Markdown

Purpose Markdown Rendered HTML
Bold text **Bold Text** Bold Text
Italic text *Italic Text* Italic Text
Headings # Level 1, ## Level 2, ### Level 3, ...
External link [website of TU Dresden](https://tu-dresden.de) website of TU Dresden
Internal link [Slurm page](../jobs_and_resources/slurm.md) Slurm page
Internal link to section [section on batch jobs](../jobs_and_resources/slurm.md#batch-jobs) section on batch jobs

Further tips can be found on this cheat sheet.

Graphics and Attachments

Please use images and graphics for illustration purposes and to improve comprehensibility. All graphics and attachments are saved within misc directory of the respective subdirectory in docs.

Syntax

The syntax to insert a graphic or attachment into a page is

![Alternative text](misc/graphics_file.png)
{: align="center"}

The attribute align is optional. By default, graphics are left-aligned. Note: It is crucial to have {: align="center"} on a new line. It is possible to add captions for tables and figures using {: summary="This is a table caption"}. The summary and align parameters can be combined as well: {: summary="This is a table caption" align="top"}.

Warning

Do not add large binary files or high-resolution images to the repository. See this valuable document for image optimization.

Special Feature: Admonitions

Admonitions, also known as call-outs, may be actively used to highlight examples, warnings, tips, important information, etc. Admonitions are an excellent choice for including side content without significantly interrupting the document flow.

Several different admonitions are available within the used material theme, e.g., note, info, example, tip, warning, and cite. Please refer to the documentation page for a comprehensive overview.

Syntax

All admonitions blocks start with !!! <type> and the following content block is indented by (exactly) four spaces. If no title is provided, the title corresponds to the admonition type.

!!! note "Descriptive title"

    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod
    tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At
    vero eos et accusam et justo duo dolores et ea rebum.

Note

Admonitions can be made foldable by using ??? instead of !!!. A small toggle on the right side is displayed. The block is open by default if ???+ is used. Long code examples should be folded by default.

Spelling and Technical Wording

To provide consistent and high-quality documentation, and help users to find the right pages, there is a list of conventions w.r.t. spelling and technical wording.

  • Language settings: en_us
Do Don't
I/O IO
Slurm SLURM
filesystem(s) file system(s)
ZIH system(s) Taurus, HRSK II, our HPC systems, etc.
workspace work space
HPC-DA
partition ml ML partition, ml partition, ml partition, "ml" partition, etc.

Code Blocks and Command Prompts

  • Use ticks to mark code blocks and commands, not an italic font.
  • Specify language for code blocks (see below).
  • All code blocks and commands should be runnable from a login node or a node within a specific partition (e.g., ml).
  • It should be clear from the prompt, where the command is run (e.g., local machine, login node, or specific partition).

Code Blocks and Syntax Highlighting

Providing code blocks and snippets is the meat and bones of this documentation. Code blocks and command examples should give the general idea of invocation and be as precise as possible, i.e., allowing for copy-and-paste. Please mark replaceable code parts and optional and required arguments as outlined in the section required and optional arguments below. Long, non-meaningful output should be omitted.

We make use of the extension pymdownx.highlight for syntax highlighting. There is a complete list of supported language short codes.

Syntax for command line

For normal commands executed in the terminal, use the language short code console.

```console
marie@login$ module list
[...]
```
Syntax for job files and scripts

Use the language short code bash for job files and shell scripts.

```bash
#!/bin/bash
#SBATCH --nodes=1
#SBATCH --time=01:00:00
#SBATCH --output=slurm-%j.out

module load foss

srun a.out
```
Syntax for Python

python for Python source code:

```python
from time import gmtime, strftime
print(strftime("%Y-%m-%d %H:%M:%S", gmtime()))
```

And pycon for Python console:

```pycon
>>> from time import gmtime, strftime
>>> print(strftime("%Y-%m-%d %H:%M:%S", gmtime()))
2021-08-03 07:20:33
```
Line numbers

More sugar can be applied by adding line numbers.

```bash linenums="1"
#!/bin/bash

#SBATCH --nodes=1
#SBATCH --ntasks=23
#SBATCH --time=02:10:00

srun a.out
```

Result:

lines

Specific Lines can be highlighted by using

```bash hl_lines="2 3"
#!/bin/bash

#SBATCH --nodes=1
#SBATCH --ntasks=23
#SBATCH --time=02:10:00

srun a.out
```

Result:

lines

Data Privacy and Generic Names

Where possible, replace login, project name, and other private data with clearly recognizable placeholders. In particular, use the generic login marie and the project title p_number_crunch as placeholders.

marie@login$ ls -l
drwxr-xr-x   3 marie p_number_crunch      4096 Jan 24  2020 code
drwxr-xr-x   3 marie p_number_crunch      4096 Feb 12  2020 data
-rw-rw----   1 marie p_number_crunch      4096 Jan 24  2020 readme.md

Placeholders

Placeholders represent arguments or code parts that can be adapted to the user's needs. Use them to give a general idea of how a command or code snippet can be used, e. g. to explain the meaning of some command argument:

marie@login$ sacct -j <job id>

Here, a placeholder explains the intention better than just a specific value:

marie@login$ sacct -j 4041337

Please be aware, that a reader often understands placeholders easier if you also give an example. Therefore, always add an example!

Mark Omissions

If showing only a snippet of a long output, omissions are marked with [...].

Unix Rules

Stick to the Unix rules on optional and required arguments, and selection of item sets:

  • <required argument or value>
  • [optional argument or value]
  • {choice1|choice2|choice3}

List of Prompts

We follow these rules regarding prompts to make clear where a certain command or example is executed. This should help to avoid errors.

Host/Partition Prompt
Localhost marie@local$
Login nodes marie@login$
Arbitrary compute node marie@compute$
haswell partition marie@haswell$
ml partition marie@ml$
alpha partition marie@alpha$
romeo partition marie@romeo$
julia partition marie@julia$
dcv partition marie@dcv$
  • Always use a prompt, even if there is no output provided for the shown command.
  • All code blocks which specify some general command templates, e.g. containing < and > (see placeholders and Unix rules), should use bash for the code block. Additionally, an example invocation, perhaps with output, should be given with the normal console code block. See also Code Block description below.
  • Using some magic, the prompt as well as the output is identified and will not be copied!
  • Stick to the generic user name marie.

Long Options

The general rule is to provide long over short parameter names where possible to ease understanding. This holds especially for Slurm options, but also other commands.

Example
Do Don't
srun --nodes=2 --ntasks-per-node=4 [...] srun -N 2 -n 4 [...]
module load [...] ml [...]