Skip to content

Content Rules

Remark: Avoid using tabs both in markdown files and in mkdocs.yaml. Type spaces instead.

New Page and Pages Structure

The pages structure is defined in the configuration file mkdocs.yaml:

docs/
  - Home: index.md
  - Application for HPC Login: application.md
  - Request for Resources: req_resources.md
  - Access to the Cluster: access.md
  - Available Software and Usage:
    - Overview: software/overview.md
  [...]

To add a new page to the documentation follow these two steps:

  1. Create a new markdown file under docs/subdir/file_name.md and put the documentation inside. The sub-directory and file name should follow the pattern fancy_title_and_more.md.
  2. Add subdir/file_name.md to the configuration file mkdocs.yml by updating the navigation section.

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

Markdown

  1. Please keep things simple, i.e., avoid using fancy markdown dialects.

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

  3. Admonitions may be actively used, especially for longer code examples, warnings, tips, important information that should be highlighted, etc. Code examples, longer than half screen height should collapsed (and indented):

Example
[...]
# very long example here
[...]

Writing Style

  • Capitalize headings, e.g. Exclusive Reservation of Hardware
  • Give keywords in link texts, e.g. Code Blocks is more descriptive than this subsection
  • 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.

Spelling and Technical Wording

To provide a 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
  • I/O not IO
  • Slurm not SLURM
  • Filesystem not file system
  • ZIH system and ZIH systems not Taurus, HRSKII, our HPC systems, etc.
  • Workspace not work space
  • avoid term HPC-DA
  • Partition names after the keyword partition: partition ml not ML partition, ml partition, ml partition, "ml" partition, etc.

Long Options

  • Use long over short options, e.g. srun --nodes=2 --ntasks-per-node=4 ... is preferred over srun -N 2 -n 4 ...
  • Use module over the short front-end ml in documentation and examples

Code Blocks and Command Prompts

Showing commands and sample output is an important part of all technical documentation. To make things as clear for readers as possible and provide a consistent documentation, some rules have to be followed.

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

Prompts

We follow this rules regarding prompts:

Host/Partition Prompt
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$
Localhost marie@local$

Remarks:

  • Always use a prompt, even there is no output provided for the shown command.
  • All code blocks should use long parameter names (e.g. Slurm parameters), if available.
  • All code blocks which specify some general command templates, e.g. containing < and > (see Placeholders), 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.

Code Blocks and Syntax Highlighting

This project makes use of the extension pymdownx.highlight for syntax highlighting. There is a complete list of supported language short codes.

For consistency, use the following short codes within this project:

With the exception of command templates, use console for shell session and console:

```console
marie@login$ ls
foo
bar
```

Make sure that shell session and console code blocks are executable on the login nodes of HPC system.

Command templates use Placeholders to mark replaceable code parts. Command templates should give a general idea of invocation and thus, do not contain any output. Use a bash code block followed by an invocation example (with console):

```bash
marie@local$ ssh -NL <local port>:<compute node>:<remote port> <zih login>@tauruslogin.hrsk.tu-dresden.de
```

```console
marie@local$ ssh -NL 5901:172.24.146.46:5901 marie@tauruslogin.hrsk.tu-dresden.de
```

Also use bash for shell scripts such as job files:

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

module load foss

srun a.out
```

Important

Use long parameter names where possible to ease understanding.

python for Python source code:

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

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 can be added via

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

#SBATCH -N 1
#SBATCH -n 23
#SBATCH -t 02:10:00

srun a.out
```

Result:

lines

Specific Lines can be highlighted by using

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

#SBATCH -N 1
#SBATCH -n 23
#SBATCH -t 02:10:00

srun a.out
```

Result:

lines

Data Privacy and Generic User Name

Where possible, replace login, project name and other private data with clearly arbitrary placeholders. E.g., use the generic login marie and the corresponding project name p_marie.

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

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}

Graphics and Attachments

All graphics and attachments are saved within misc directory of the respective sub directory in docs.

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

![PuTTY: Switch on X11](misc/putty2.jpg)
{: 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.