merge preview

doc.zih.tu-dresden.de/docs/contrib/content_guide_lines.md

@@ -43,7 +43,7 @@ or via [Email](mailto:hpcsupport@zih.tu-dresden.de).
 
 * All documentation is written in [Markdown](#markdown).
 * Type spaces (not tabs) both in Markdown files and in `mkdocs.yml`.
-* Respect the line limit of 100 characters (except for links).
+* Respect the line limit of 100 characters (exception: links).
 * Do not add large binary files or high resolution images to the repository (cf.
    [adding images and attachments](#grapics-and-attachments)).
 * [Admonitions](#admonitions) may be actively used for longer code examples, warnings, tips,
@@ -62,20 +62,20 @@ or via [Email](mailto:hpcsupport@zih.tu-dresden.de).
 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):
 
-| Heading | File |
-| --- | --- |
-| 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 |
+```Markdown
+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:
 
@@ -104,12 +104,12 @@ Markdown dialects.
 | 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) |
 
-Further tips here: [Cheat Sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
+Further tips can be found at this
+[cheat sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
 
 #### Graphics and Attachments
 
-Please use graphics for understandability.
-
+Please use images and graphics for illustration purposes and to improve understandability.
 All graphics and attachments are saved within `misc` directory of the respective sub directory in
 `docs`.
 
@@ -163,22 +163,28 @@ for a comprehensive overview.
 
 !!! node 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.
+    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.
 
 ### Writing Style
 
-* Avoid using tabs both in markdown files and in `mkdocs.yaml`. Type spaces instead.
-* Capitalize headings, e.g. *Exclusive Reservation of Hardware*
-* 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).
+* 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.`
-* 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
+* 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