diff --git a/doc.zih.tu-dresden.de/docs/contrib/content_rules.md b/doc.zih.tu-dresden.de/docs/contrib/content_rules.md
index 8813093f4274220e7b94d9fdc110f8057b71b3a4..24ee96ffe2ea39cf2caa95fedfc205c4e0129439 100644
--- a/doc.zih.tu-dresden.de/docs/contrib/content_rules.md
+++ b/doc.zih.tu-dresden.de/docs/contrib/content_rules.md
@@ -1,6 +1,23 @@
# Content Rules
-## Responsibility And License
+!!! cite "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](../legal_notice.md)):
@@ -11,60 +28,89 @@ These licenses also apply to your contributions.
!!! note
- Each user is fully and solely responsible for the content he/she creates and has to ensure that
- he/she has the right to create it under the laws which apply.
+ 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](https://gitlab.hrz.tu-chemnitz.de/zih/hpcsupport/hpc-compendium/-/issues)
or via [Email](mailto:hpcsupport@zih.tu-dresden.de).
-## New Page and Pages Structure
+## Quick Overview
+
+* All documentation is written in [Markdown](#markdown).
+* Use spaces (not tabs) both in Markdown files and in `mkdocs.yml`.
+* Respect the line length limit of 100 characters (exception: links).
+* Do not add large binary files or high-resolution images to the repository (cf.
+ [adding images and attachments](#graphics-and-attachments)).
+* [Admonitions](#special-feature-admonitions) may be actively used for longer code examples,
+ warnings, tips, important information, etc.
+* Respect the [writing style](#writing-style) and the rules for
+ [spelling and technical wording](#spelling-and-technical-wording).
+* For code blocks:
+ * Use [syntax highlighting and appropriate prompts](#code-blocks-and-command-prompts).
+ * Respect [data privacy](#data-privacy-and-generic-names).
+ * Stick to the [rules on optional and required arguments](#unix-rules).
+
+## Detailed Overview
-The pages structure is defined in the configuration file `mkdocs.yaml`:
+### Writing Style
-```Bash
-docs/
+* 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](#code-blocks-and-syntax-highlighting) is more
+ descriptive than [this subsection](#code-blocks-and-syntax-highlighting)
+* 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`](https://gitlab.hrz.tu-chemnitz.de/zih/hpcsupport/hpc-compendium/-/blob/main/doc.zih.tu-dresden.de/mkdocs.yml):
+
+```Markdown
+nav:
- 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
+ - 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
[...]
```
-To add a new page to the documentation follow these two steps:
+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 and file name should follow the pattern `fancy_title_and_more.md`.
+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`.
1. Add `subdir/file_name.md` to the configuration file `mkdocs.yml` by updating the navigation
- section.
+ 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
-
-1. Please keep things simple, i.e., avoid using fancy markdown dialects.
- * [Cheat Sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
- * [Style Guide](https://github.com/google/styleguide/blob/gh-pages/docguide/style.md)
+### Markdown
-1. Do not add large binary files or high resolution images to the repository. See this valuable
- document for [image optimization](https://web.dev/fast/#optimize-your-images).
+All documentation is written in Markdown. Please keep things simple, i.e., avoid using fancy
+Markdown dialects.
-1. [Admonitions](https://squidfunk.github.io/mkdocs-material/reference/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):
-
-??? "Collapsed example"
- ```Bash
- [...]
- # very long example here
- [...]
- ```
-
-### Brief How-To on Markdown
+#### Brief How-To on Markdown
| Purpose | Markdown | Rendered HTML |
|---|---|---|
@@ -75,198 +121,197 @@ should be highlighted, etc. Code examples, longer than half screen height should
| Internal link | `[Slurm page](../jobs_and_resources/slurm.md)` | [Slurm page](../jobs_and_resources/slurm.md)|
| Internal link to section | `[section on batch jobs](../jobs_and_resources/slurm.md#batch-jobs)` | [section on batch jobs](../jobs_and_resources/slurm.md#batch-jobs) |
-## Writing Style
+Further tips can be found on this
+[cheat sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
-* 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, 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](#code-blocks-and-syntax-highlighting) is more
- descriptive than [this subsection](#code-blocks-and-syntax-highlighting)
-* Avoid using tabs both in markdown files and in `mkdocs.yaml`. Type spaces instead.
+#### Graphics and Attachments
-## Spelling and Technical Wording
+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`.
-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.
+!!! example "Syntax"
-* 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.
+ The syntax to insert a graphic or attachment into a page is
-### Long Options
+ ```markdown
+ 
+ {: align="center"}
+ ```
-* 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
+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"}`.
-## Code Blocks and Command Prompts
+!!! warning
-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.
+ Do not add large binary files or high-resolution images to the repository. See this valuable
+ document for [image optimization](https://web.dev/fast/#optimize-your-images).
-1. Use ticks to mark code blocks and commands, not italic font.
-1. Specify language for code blocks ([see below](#code-blocks-and-syntax-highlighting)).
-1. All code blocks and commands should be runnable from a login node or a node within a specific
- partition (e.g., `ml`).
-1. It should be clear from the prompt, where the command is run (e.g. local machine, login node or
- specific partition).
+#### Special Feature: Admonitions
-### Prompts
+[Admonitions](https://squidfunk.github.io/mkdocs-material/reference/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.
-We follow this rules regarding prompts:
+Several different admonitions are available within the used
+[material theme](https://squidfunk.github.io/mkdocs-material/), e.g., `note`, `info`, `example`,
+`tip`, `warning`, and `cite`. Please refer to the
+[documentation page](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types)
+for a comprehensive overview.
-| 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$` |
-| `dcv` partition | `marie@dcv$` |
-| Localhost | `marie@local$` |
+!!! example "Syntax"
-*Remarks:*
+ 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.
-* **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](#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](#code-blocks-and-syntax-highlighting).
-* Using some magic, the prompt as well as the output is identified and will not be copied!
-* Stick to the [generic user name](#data-privacy-and-generic-names) `marie`.
+ ```markdown
+ !!! note "Descriptive title"
-### Code Blocks and Syntax Highlighting
+ 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.
+ ```
-This project makes use of the extension
-[pymdownx.highlight](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/) for syntax
-highlighting. There is a complete list of supported
-[language short codes](https://pygments.org/docs/lexers/).
+!!! note Folding
-For consistency, use the following short codes within this project:
+ 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.
-With the exception of command templates, use `console` for shell session and console:
+### Spelling and Technical Wording
-````markdown
-```console
-marie@login$ ls
-foo
-bar
-```
-````
+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.
-Make sure that shell session and console code blocks are executable on the login nodes of HPC system.
+* Language settings: en_us
-Command templates use [Placeholders](#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`):
+| 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](#code-blocks-and-syntax-highlighting)).
+* 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](#list-of-prompts), 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](#unix-rules) below.
+Long, non-meaningful output should be omitted.
+
+We make use of the extension
+[pymdownx.highlight](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/) for syntax
+highlighting. There is a complete list of supported
+[language short codes](https://pygments.org/docs/lexers/).
-````markdown
-```bash
-marie@local$ ssh -NL <local port>:<compute node>:<remote port> taurus
-```
+??? note "Syntax for command line"
-```console
-marie@local$ ssh -NL 5901:172.24.146.46:5901 taurus
-```
-````
+ For normal commands executed in the terminal, use the language short code `console`.
-Also use `bash` for shell scripts such as job files:
+ ````markdown
+ ```console
+ marie@login$ module list
+ [...]
+ ```
+ ````
-````markdown
-```bash
-#!/bin/bash
-#SBATCH --nodes=1
-#SBATCH --time=01:00:00
-#SBATCH --output=slurm-%j.out
+??? note "Syntax for job files and scripts"
-module load foss
+ Use the language short code `bash` for job files and shell scripts.
-srun a.out
-```
-````
+ ````markdown
+ ```bash
+ #!/bin/bash
+ #SBATCH --nodes=1
+ #SBATCH --time=01:00:00
+ #SBATCH --output=slurm-%j.out
-!!! important
+ module load foss
- Use long parameter names where possible to ease understanding.
+ srun a.out
+ ```
+ ````
-`python` for Python source code:
+??? note "Syntax for Python"
-````markdown
-```python
-from time import gmtime, strftime
-print(strftime("%Y-%m-%d %H:%M:%S", gmtime()))
-```
-````
+ `python` for Python source code:
-`pycon` for Python console:
+ ````markdown
+ ```python
+ from time import gmtime, strftime
+ print(strftime("%Y-%m-%d %H:%M:%S", gmtime()))
+ ```
+ ````
-````markdown
-```pycon
->>> from time import gmtime, strftime
->>> print(strftime("%Y-%m-%d %H:%M:%S", gmtime()))
-2021-08-03 07:20:33
-```
-````
+ And `pycon` for Python console:
-Line numbers can be added via
+ ````markdown
+ ```pycon
+ >>> from time import gmtime, strftime
+ >>> print(strftime("%Y-%m-%d %H:%M:%S", gmtime()))
+ 2021-08-03 07:20:33
+ ```
+ ````
-````markdown
-```bash linenums="1"
-#!/bin/bash
+??? note "Line numbers"
-#SBATCH --nodes=1
-#SBATCH --ntasks=23
-#SBATCH --time=02:10:00
+ More sugar can be applied by adding line numbers.
-srun a.out
-```
-````
+ ````markdown
+ ```bash linenums="1"
+ #!/bin/bash
-_Result_:
+ #SBATCH --nodes=1
+ #SBATCH --ntasks=23
+ #SBATCH --time=02:10:00
-
+ srun a.out
+ ```
+ ````
-Specific Lines can be highlighted by using
+ _Result_:
-```` markdown
-```bash hl_lines="2 3"
-#!/bin/bash
+ 
-#SBATCH --nodes=1
-#SBATCH --ntasks=23
-#SBATCH --time=02:10:00
+ Specific Lines can be highlighted by using
-srun a.out
-```
-````
+ ```` markdown
+ ```bash hl_lines="2 3"
+ #!/bin/bash
+
+ #SBATCH --nodes=1
+ #SBATCH --ntasks=23
+ #SBATCH --time=02:10:00
-_Result_:
+ srun a.out
+ ```
+ ````
+
+ _Result_:
-
+ 
-### Data Privacy and Generic Names
+#### Data Privacy and Generic Names
-Where possible, replace login, project name and other private data with clearly recognizable
+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.
@@ -296,7 +341,11 @@ 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!
-##### Unix Rules
+#### 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:
@@ -304,25 +353,40 @@ Stick to the Unix rules on optional and required arguments, and selection of ite
* `[optional argument or value]`
* `{choice1|choice2|choice3}`
-#### Mark Omissions
+#### List of Prompts
-If showing only a snippet of a long output, omissions are marked with `[...]`.
+We follow these rules regarding prompts to make clear where a certain command or example is executed.
+This should help to avoid errors.
-## Graphics and Attachments
+| 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$` |
-All graphics and attachments are saved within `misc` directory of the respective sub directory in
-`docs`.
+* **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](#placeholders) and [Unix rules](#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](#code-blocks-and-syntax-highlighting).
+* Using some magic, the prompt as well as the output is identified and will not be copied!
+* Stick to the [generic user name](#data-privacy-and-generic-names) `marie`.
-The syntax to insert a graphic or attachment into a page is
+#### Long Options
-```Bash
-
-{: align="center"}
-```
+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.
-The attribute `align` is optional. By default, graphics are left aligned. **Note:** It is crucial to
-have `{: align="center"}` on a new line.
+??? example
-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"}`.
+ | Do | Don't |
+ |----|-------|
+ | `srun --nodes=2 --ntasks-per-node=4 [...]`| `srun -N 2 -n 4 [...]` |
+ | `module load [...]` | `ml [...]` |
diff --git a/doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md b/doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md
index 4a14f2d245a481e9a1a3cdfd2abccdd5a63efa4a..6f3303e98debc9888a25600121f14e086896b7a4 100644
--- a/doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md
+++ b/doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md
@@ -4,16 +4,20 @@
Ink is better than the best memory.
-Even though we try to cover all aspects of working with the ZIH systems and keep the documentation
-up to date, you might miss something. In principle, there are three possible ways how you can
-contribute to this documentation as outlined below.
+This documentation is written in markdown and translated into static html pages using
+[mkdocs](https://www.mkdocs.org/). A single configuration file holds the pages structure
+as well as specification of the theme and extensions. This file is `mkdocs.yaml`.
-## Content Rules
+All essential files (markdown pages, graphics, configuration, theme, etc.) are managed within a Git
+repository which makes it quite easy to contribute to this documentation. In principle, there are
+three possible ways how to contribute to this documentation. These ways are outlined below.
+
+## Content Guide Lines
To ensure a high-quality and consistent documentation and to make it easier for readers to
-understand all content, we set some [content rules](content_rules.md). Please follow these rules
-when contributing! Furthermore, reviewing your changes take less time and your improvements appear
-faster on the official documentation.
+understand all content, we set some [Content rules](content_rules.md). Please follow
+these rules regarding markdown syntax and writing style when contributing! Furthermore, reviewing
+your changes take less time and your improvements appear faster on the official documentation.
!!! note
@@ -51,4 +55,4 @@ For experienced Git users, we provide a Docker container that includes all check
used in the back-end. Using them should ensure that merge requests will not be blocked
due to automatic checking.
The page on [Contributing via local clone](contribute_container.md) provides you with the details
-about how to setup and use your local clone.
+about how to setup and use your local clone of the repository.