From 16d8596b592bc848568be6863da1527a4e3ce13f Mon Sep 17 00:00:00 2001
From: Martin Schroschk <martin.schroschk@tu-dresden.de>
Date: Fri, 7 Jan 2022 08:49:15 +0100
Subject: [PATCH] Update
---
.../docs/contrib/content_rules.md | 195 ++++++++++++------
.../docs/contrib/howto_contribute.md | 11 +-
2 files changed, 143 insertions(+), 63 deletions(-)
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 2be83c1f7..ac9d6ca33 100644
--- a/doc.zih.tu-dresden.de/docs/contrib/content_rules.md
+++ b/doc.zih.tu-dresden.de/docs/contrib/content_rules.md
@@ -1,62 +1,141 @@
-# Content Rules
+# Content Guide Lines
-**Remark:** Avoid using tabs both in markdown files and in `mkdocs.yaml`. Type spaces instead.
+!!! cite "George Bernard Shaw"
+
+ The golden rule is that there are no golden rules.
+
+!!! cite "Proverb"
+
+ There is an exception to every rule.
-## New Page and Pages Structure
+This page holds <del>rules</del> guide lines 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, it need some guide lines which are
+outlined in the following.
+
+## Pages Structure and New Page
The pages structure is defined in the configuration file `mkdocs.yaml`:
```Bash
-docs/
+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: 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
+ - 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. 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)
+All this documentation is written in markdown. 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
- document for [image optimization](https://web.dev/fast/#optimize-your-images).
+### Graphics and Attachments
-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):
+Images and graphics are an important part of technical documentation. This also holds for this HPC
+compendium. Thus, we encourage you to add images and graphics for illustration purposes.
-??? example
- ```Bash
- [...]
- # very long example here
- [...]
+Attachments may be used to provide a more detailed documentation or further outline a certain
+process and topic.
+
+All images, graphics and attachments are stored in the `misc` subdirectory of the corresponding
+section.
+
+!!! example "Syntax"
+
+ ```markdown
+ 
+ {: 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.
+
+!!! warning
+
+ 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).
+
+
+### Admonitions
+
+[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.
+
+Several different admonitions are available within the material theme, 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.
+
+All admonitions blocks start with `!!! <type>` and the following content block is indented by
+(exactly) four spaces.
+
+!!! example "Syntax"
+
+ ```markdown
+ !!! note
+
+ 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.
+ ```
+
+#### Folding
+
+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.
+
+#### Title
+
+The title corresponds to the admonition type. However, the title of an admonition can be changed for
+further decoration by providing the desired title as quoted string after the type qualifier.
+
+```markdown
+
+!!! note "Random 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.
+```
+
## Writing Style
* 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)
+* Give keywords in link texts, e.g. [Code Blocks](#code-blocks-and-syntax-highlighting) is way more
+ descriptive than [this subsection](#code-blocks-and-syntax-highlighting).
* 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.`
+* Write directly to the readers/users, e.g., use `you can/have` instead of `users can/have`
+* If there are multiple ways of doing things, recommend one over the others and justify
## Spelling and Technical Wording
@@ -64,37 +143,46 @@ To provide a consistent and high quality documentation, and help users to find t
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
+| Do | Don't |
+|----|-------|
+| I/O | IO |
+| Slurm | SLURM |
+| filesystem(s) | file system(s) |
+| ZIH system(s) | Taurus, HRSKII, our HPC systems, etc. |
+| workspace | work space |
+| | HPC-DA |
+| partition `ml` | ML partition, ml partition, `ml` partition, "ml" partition, etc. |
+
-* 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
+things as clear for readers as possible and provide a consistent documentation, some guide lines have to
be followed.
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).
+1. It should be clear from the [prompt](#prompts), where the command is run (e.g., local machine,
+ login node or specific partition).
+
+### Long Options
+
+We use long over short parameter names where possible to ease understanding.
+
+!!! example
+
+ `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.
### Prompts
-We follow this rules regarding prompts:
+We follow this rules regarding prompts to make clear where a certain command or example is executed.
+This should help to avoid errors.
| Host/Partition | Prompt |
|------------------------|------------------|
@@ -107,10 +195,7 @@ We follow this rules regarding prompts:
| `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](#mark-placeholders)), should use `bash` for the code block. Additionally,
an example invocation, perhaps with output, should be given with the normal `console` code block.
@@ -168,9 +253,6 @@ srun a.out
```
````
-!!! important
-
- Use long parameter names where possible to ease understanding.
`python` for Python source code:
@@ -251,17 +333,6 @@ Stick to the Unix rules on optional and required arguments, and selection of ite
* `[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
+## Random things
-```Bash
-
-{: 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.
+**Remark:** Avoid using tabs both in markdown files and in `mkdocs.yaml`. Type spaces instead.
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 e0d91cccc..e2e11cbdd 100644
--- a/doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md
+++ b/doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md
@@ -4,7 +4,16 @@
Ink is better than the best memory.
-In principle, there are three possible ways how to contribute to this documentation.
+This documentation is written in markdown and translated into static html pages using
+[mkdocs](https://www.mkdocs.org/). There is a single configuration file holding the pages structure
+as well as specification of the theme and extensions. This file is `mkdocs.yaml`.
+
+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.
+
+Please refer to the [content guide lines page](content_guide_lines.md) regarding markdown syntax
+and writing style.
## Contribute via Issue
--
GitLab