From 1ea6794fdda5d88513867e19281b8cbe8e33b328 Mon Sep 17 00:00:00 2001
From: Martin Schroschk <martin.schroschk@tu-dresden.de>
Date: Wed, 9 Jun 2021 10:30:41 +0200
Subject: [PATCH] Add issue on writing
---
doc.zih.tu-dresden.de/CONTRIBUTE.md | 43 +++++++++++++++++------------
1 file changed, 26 insertions(+), 17 deletions(-)
diff --git a/doc.zih.tu-dresden.de/CONTRIBUTE.md b/doc.zih.tu-dresden.de/CONTRIBUTE.md
index 30dc602eb..da7c526f9 100644
--- a/doc.zih.tu-dresden.de/CONTRIBUTE.md
+++ b/doc.zih.tu-dresden.de/CONTRIBUTE.md
@@ -294,6 +294,9 @@ ERROR: 2 dead links found!
### Check Code and Commands
+1. All code blocks and commands should be runnable from a login node.
+1.
+
**TODO:** Implement [Issue #9](#9)
### Check Pages Structure
@@ -347,7 +350,7 @@ there is a list of conventions w.r.t. spelling and technical wording.
**TODO:** Implement checks [Issue #13](#13)
-### Command Prompts
+### Code Blocks and Command Prompts
Showing commands and sample output is an important part of all technical documentation. Thus, some
rules have to be followed.
@@ -355,33 +358,39 @@ rules have to be followed.
1. Prompts: It should be clear from the prompt, where the command is run (e.g. Taurus, specific
partition or local machine).
- * Taurus / HPC systems of TUD in general: `taurus$`
- * Specific kind of node or partition: `tauruslogin$`, `taurus-ml$` `taurus-rome$`etc.
- * TODO: Remove prefix `taurus`?
- * Local machine: `localhost$`
+ * Taurus / HPC systems of TUD in general: `taurus$`
+ * Specific kind of node or partition: `tauruslogin$`, `taurus-ml$` `taurus-rome$`etc.
+ * TODO: Remove prefix `taurus`?
+ * Local machine: `localhost$`
+ * No output: Omit prompt (copy-paste)
+ * With Output: Add prompt (make clear what is the command and what is the output)
+
+### Data Privacy and Generic User Name
-1. Use generic user name, e.g. `zwulf`:
-```shell
+Where possible, replace user, project and other private data with clearly arbitrary placeholders.
+E.g., use generic user and project name.
+
+```Shell Session
taurus$ ls -l
drwxr-xr-x 3 zwulf p_zwulf 4096 Jan 24 2020 code
drwxr-xr-x 3 zwulf p_zwulf 4096 Feb 12 2020 data
-rw-rw---- 1 zwulf p_zwulf 4096 Jan 24 2020 readme.md
```
-1. Schere: If showing only a snippet of a long output, omissions are marked with
+### Mark Omissions
+
+If showing only a snippet of a long output, omissions are marked with
* `8< 8<`
* `[snip]`
* `[...]`
- * TODO: Choose one.
-
-### Code Blocks
-
-All code blocks should be runnable from a login node.
-
-
-
-
+**TODO:** Choose one!
+### Mark Placeholders
+Stick to the Unix rules on optional and required arguments.
+```Shell Session
+<required argument or value>
+[optional argument or value]
+```
--
GitLab