Skip to content
Snippets Groups Projects
Commit 58a70659 authored by Taras Lazariv's avatar Taras Lazariv
Browse files

Merge branch 'content-rules' into 'preview' 

Content rules

Closes #6

See merge request !554
parents 5b0b4e4c 71876b03
No related branches found
No related tags found
2 merge requests!592Automated merge from preview to main,!554Content rules
Hide whitespace changes
Inline Side-by-side
doc.zih.tu-dresden.de/docs/contrib/content_rules.md
+ 261
− 197
View file @ 58a70659
# Content Rules # 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)): 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. ...@@ -11,60 +28,89 @@ These licenses also apply to your contributions.
!!! note !!! note
Each user is fully and solely responsible for the content he/she creates and has to ensure that If you contribute, you are fully and solely responsible for the content you create and have to
he/she has the right to create it under the laws which apply. ensure that you have the right to create it under the laws which apply.
If you are in doubt, please contact us either via If you are in doubt, please contact us either via
[GitLab Issue](https://gitlab.hrz.tu-chemnitz.de/zih/hpcsupport/hpc-compendium/-/issues) [GitLab Issue](https://gitlab.hrz.tu-chemnitz.de/zih/hpcsupport/hpc-compendium/-/issues)
or via [Email](mailto:hpcsupport@zih.tu-dresden.de). 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 * Assume that a future reader is eager to start typing commands. Thus, encourage the reader by
docs/ 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 - Home: index.md
- Application for HPC Login: application.md - Application for Login and Resources:
- Request for Resources: req_resources.md - Overview: application/overview.md
- Access to the Cluster: access.md - Terms of Use: application/terms_of_use.md
- Available Software and Usage: - Request for Resources: application/request_for_resources.md
- Overview: software/overview.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. 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`. 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 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 Make sure that the new page **is not floating**, i.e., it can be reached directly from
the documentation structure. the documentation structure.
## Markdown ### 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)
1. Do not add large binary files or high resolution images to the repository. See this valuable All documentation is written in Markdown. Please keep things simple, i.e., avoid using fancy
document for [image optimization](https://web.dev/fast/#optimize-your-images). Markdown dialects.
1. [Admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) may be #### Brief How-To on Markdown
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
| Purpose | Markdown | Rendered HTML | | Purpose | Markdown | Rendered HTML |
|---|---|---| |---|---|---|
...@@ -75,198 +121,197 @@ should be highlighted, etc. Code examples, longer than half screen height should ...@@ -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 | `[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) | | 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 #### Graphics and Attachments
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.
## 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, !!! example "Syntax"
there is a list of conventions w.r.t. spelling and technical wording.
* Language settings: en_us The syntax to insert a graphic or attachment into a page is
* `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 ```markdown
![Alternative text](misc/graphics_file.png)
{: align="center"}
```
* Use long over short options, e.g. `srun --nodes=2 --ntasks-per-node=4 ...` is preferred over The attribute `align` is optional. By default, graphics are left-aligned. **Note:** It is crucial to
`srun -N 2 -n 4 ...` have `{: align="center"}` on a new line.
* Use `module` over the short front-end `ml` in documentation and examples 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 Do not add large binary files or high-resolution images to the repository. See this valuable
things as clear for readers as possible and provide a consistent documentation, some rules have to document for [image optimization](https://web.dev/fast/#optimize-your-images).
be followed.
1. Use ticks to mark code blocks and commands, not italic font. #### Special Feature: Admonitions
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).
### 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 | !!! example "Syntax"
|------------------------|------------------|
| 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$` |
*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. ```markdown
* All code blocks should use long parameter names (e.g. Slurm parameters), if available. !!! note "Descriptive title"
* 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`.
### 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 !!! note Folding
[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/).
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 To provide consistent and high-quality documentation, and help users to find the right pages,
```console there is a list of conventions w.r.t. spelling and technical wording.
marie@login$ ls
foo
bar
```
````
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 | Do | Don't |
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`): | 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 ??? note "Syntax for command line"
```bash
marie@local$ ssh -NL <local port>:<compute node>:<remote port> taurus
```
```console For normal commands executed in the terminal, use the language short code `console`.
marie@local$ ssh -NL 5901:172.24.146.46:5901 taurus
```
````
Also use `bash` for shell scripts such as job files: ````markdown
```console
marie@login$ module list
[...]
```
````
````markdown ??? note "Syntax for job files and scripts"
```bash
#!/bin/bash
#SBATCH --nodes=1
#SBATCH --time=01:00:00
#SBATCH --output=slurm-%j.out
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` for Python source code:
```python
from time import gmtime, strftime
print(strftime("%Y-%m-%d %H:%M:%S", gmtime()))
```
````
`pycon` for Python console: ````markdown
```python
from time import gmtime, strftime
print(strftime("%Y-%m-%d %H:%M:%S", gmtime()))
```
````
````markdown 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 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 ??? note "Line numbers"
```bash linenums="1"
#!/bin/bash
#SBATCH --nodes=1 More sugar can be applied by adding line numbers.
#SBATCH --ntasks=23
#SBATCH --time=02:10:00
srun a.out ````markdown
``` ```bash linenums="1"
```` #!/bin/bash
_Result_: #SBATCH --nodes=1
#SBATCH --ntasks=23
#SBATCH --time=02:10:00
![lines](misc/lines.png) srun a.out
```
````
Specific Lines can be highlighted by using _Result_:
```` markdown ![lines](misc/lines.png)
```bash hl_lines="2 3"
#!/bin/bash
#SBATCH --nodes=1 Specific Lines can be highlighted by using
#SBATCH --ntasks=23
#SBATCH --time=02:10:00
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_:
![lines](misc/highlight_lines.png) ![lines](misc/highlight_lines.png)
### 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` placeholders. In particular, use the generic login `marie` and the project title `p_number_crunch`
as placeholders. as placeholders.
...@@ -296,7 +341,11 @@ marie@login$ sacct -j 4041337 ...@@ -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. Please be aware, that a reader often understands placeholders easier if you also give an example.
Therefore, always add 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: 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 ...@@ -304,25 +353,40 @@ Stick to the Unix rules on optional and required arguments, and selection of ite
* `[optional argument or value]` * `[optional argument or value]`
* `{choice1|choice2|choice3}` * `{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 * **Always use a prompt**, even if there is no output provided for the shown command.
`docs`. * 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 The general rule is to provide long over short parameter names where possible to ease
![PuTTY: Switch on X11](misc/putty2.jpg) understanding. This holds especially for Slurm options, but also other commands.
{: align="center"}
```
The attribute `align` is optional. By default, graphics are left aligned. **Note:** It is crucial to ??? example
have `{: align="center"}` on a new line.
It is possible to add captions for tables and figures using `{: summary="This is a table caption"}`. | Do | Don't |
The `summary` and `align` parameters can be combined as well: |----|-------|
`{: summary="This is a table caption" align="top"}`. | `srun --nodes=2 --ntasks-per-node=4 [...]`| `srun -N 2 -n 4 [...]` |
| `module load [...]` | `ml [...]` |
doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md
+ 12
− 8
View file @ 58a70659
...@@ -4,16 +4,20 @@ ...@@ -4,16 +4,20 @@
Ink is better than the best memory. 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 This documentation is written in markdown and translated into static html pages using
up to date, you might miss something. In principle, there are three possible ways how you can [mkdocs](https://www.mkdocs.org/). A single configuration file holds the pages structure
contribute to this documentation as outlined below. 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 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 understand all content, we set some [Content rules](content_rules.md). Please follow
when contributing! Furthermore, reviewing your changes take less time and your improvements appear these rules regarding markdown syntax and writing style when contributing! Furthermore, reviewing
faster on the official documentation. your changes take less time and your improvements appear faster on the official documentation.
!!! note !!! note
...@@ -51,4 +55,4 @@ For experienced Git users, we provide a Docker container that includes all check ...@@ -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 used in the back-end. Using them should ensure that merge requests will not be blocked
due to automatic checking. due to automatic checking.
The page on [Contributing via local clone](contribute_container.md) provides you with the details 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.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
Nutzungsbedingungen | Datenschutzerklärung | Barrierefreiheitserklärung