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 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 e-mail.

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.

Preserve URLs

For several reasons it is important to preserve URLs within this documentation, e.g., pages with description of specific hardware might be used as references in papers. Therefore, existing pages shall not be renamed or moved on directory level. Outdated pages are marked with "Outdated" tag and moved to the archive by changing the page's navigation entry in the mkdocs.yaml file.

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.

Attachments

Of course, you can provide attachments in sections and pages. Such attachment documents may contain information that are more detailed and go far beyond the scope of the compendium, e.g. user manuals for application-specific software.

Save attachments within the misc subdirectory of the corresponding section.

Syntax for attachments

The syntax for attachments is the very same as for links. As the attachment is within the misc subdirectory, you can refer to it as local file.

[<description>](misc/<attachment_file_name>)

Since the <description> is rendered as link text, you should choose a clear and precise text:

[slides of HPC introduction](misc/HPC-Introduction.pdf)

Graphics and Videos

Please use graphics and videos for illustration purposes and to improve comprehensibility. All graphics and attachments are saved within misc directory of the respective subdirectory in docs. For video attachments please use either webm or mp4 format. We make use of the mkdocs-video extension.

Syntax for graphics and videos

The syntax to insert a graphic into a page is

![Alternative text](misc/graphics_file.png)

The syntax to insert a video attachment into a page is

![type:video](misc/terminate-virtual-desktop-dcv.mp4)

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"}.

Resizing and Alignment of Graphics

In general, graphics and images should be added to the repository with the desired size.

Warning

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

We recommend the well-know Linux package ImageMagick for resizing graphics.

Resize image using ImageMagick

The command

marie@local$ magick cluster.jpeg -resize 600 cluster_600.jpeg

will resize the graphic cluster.jpeg to a width of 600 pixels keeping the aspect ratio. Depending on the resolution of the original file, the resulting file can be way smaller in terms of memory foot print.

Nevertheless you can explicitly specify the size a graphic. The syntax is as follows

![Alternative text](misc/graphics_file.png){: style="width:150px"}

By default, graphics are left-aligned. In most cases, this is not elegant and you probably wish to center-align your graphics. Alignment of graphics can be controlled via the {: align=<value>} attribute. Possible values are left, right and center. Note: It is crucial to have {: align=center} on a new line and the value without quotation marks.

Resize and alignment specification can be combined as depicted in the following example.

Resize image to 150px width and specify alignment

The three tabs show the Markdown syntax to resize the image of the beautiful cluster Barnard to a height of 150 pixels keeping the aspect ratio and left, center and right-align it, respectively.

![Beauty Barnard](misc/barnard.jpeg){: style="height:150px"}

Beauty Barnard

![Beauty Barnard](misc/barnard.jpeg){: style="height:150px"}
{: align="center"}

Beauty Barnard

![Beauty Barnard](misc/barnard.jpeg){: style="height:150px"}
{: align="right"}

Alternative text

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
cluster romeo ROMEO cluster, romeo cluster, romeo cluster, "romeo" cluster, 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 cluster (e.g., alpha).
  • It should be clear from the prompt, where the command is run (e.g., local machine, login node, or specific cluster).

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 placeholders depicted in the following table. The table also holds a second placeholder, if, e.g., you need a second login to formulate an example.

Description Placeholder 2nd Placeholder
Username Marie Martin
Login marie martin
E-mail marie@tu-dresden.de martin@tu-dresden.de
Project title p_number_crunch p_long_computations
Workspace title number_crunch long_computations
Job ID 123456 456789
Generic placeholders

Output of ls command

The following code listing depicts the usage of the generic user names and projects as well as recognizable placeholders for files and directory names.

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

Marie

We choose marie as generic login and placeholder. There is no magic story on this decision. Feel free to associate this generic login for example with physicist and chemist Marie Curie, and Marianne, symbol of France standing for liberty, equality and fraternity.

The very same holds for the generic login martin.

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 [...].

Code Styling Rules

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$
Compute node Capella marie@capella$
Login node Capella marie@login.capella$
Compute node Barnard marie@barnard$
Login node Barnard marie@login.barnard$
Compute node Alpha marie@alpha$
Login node Alpha marie@login.alpha$
Node Julia marie@julia$
Compute node Romeo marie@romeo$
Login node Romeo marie@login.romeo$
Compute node Power9 marie@power9$
Login node Power9 marie@login.power9$
Partition dcv 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 Code Styling 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 [...]

Equal Signs in Command-Line Options

Some tools with CLI (command-line interface) prefer specification of the argument with an equal sign (=) between the option name and the value, e.g. --long_option=value. Others prefer a whitespace, e.g. --long_option value. We respect the design decisions of the tool developers and document the desired mimic for long options. If you are in doubt, calling tool --help might provide the answer.

Tool Preference
Slurm w/ Equal sign
HPC-Workspace w/o equal sign

The documentation for the search plugin of the material theme is quite comprehensive. The search is realized as client-side search using the open-source tool on lunr. The ranking of pages in search results bases on so-called scoring. Please refer to lunrjs documentation for details.

From time to time it might be necessary to tweak the search priority of certain pages. For example, pages from the archive section should be ranked very low in search results. This can be achieved by adding the front matter search.boost property added to the top of the Markdown file of interest:

---
search:
  boost: 2
---

# Document Title

[...]

The documentation of this plugin gives no range for the boost values. We recommend to use this feature carefully starting with low values.