From de88e332fac728ca4e1af2cf0e6f0f41f06f3f26 Mon Sep 17 00:00:00 2001
From: Martin Schroschk <martin.schroschk@tu-dresden.de>
Date: Wed, 18 May 2022 10:17:38 +0200
Subject: [PATCH] merge preview
---
.../docs/contrib/content_guide_lines.md | 58 ++++++++++---------
1 file changed, 32 insertions(+), 26 deletions(-)
diff --git a/doc.zih.tu-dresden.de/docs/contrib/content_guide_lines.md b/doc.zih.tu-dresden.de/docs/contrib/content_guide_lines.md
index 3caf816aa..322f67e7f 100644
--- a/doc.zih.tu-dresden.de/docs/contrib/content_guide_lines.md
+++ b/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
--
GitLab