Skip to content
Snippets Groups Projects
Commit fdb06c93 authored by Martin Schroschk's avatar Martin Schroschk
Browse files

Move writing style topwards

parent ffc569e4
No related branches found
No related tags found
2 merge requests!592Automated merge from preview to main,!554Content rules
...@@ -53,6 +53,25 @@ or via [Email](mailto:hpcsupport@zih.tu-dresden.de). ...@@ -53,6 +53,25 @@ or via [Email](mailto:hpcsupport@zih.tu-dresden.de).
## Detailed Overview ## Detailed Overview
### Writing Style
* 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.`
* 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 ### Pages Structure and New Page
The documentation and pages structure is defined in the configuration file The documentation and pages structure is defined in the configuration file
...@@ -162,25 +181,6 @@ for a comprehensive overview. ...@@ -162,25 +181,6 @@ for a comprehensive overview.
side is displayed. The block is open by default if `???+` is used. Long code examples should be side is displayed. The block is open by default if `???+` is used. Long code examples should be
folded by default. folded by default.
### Writing Style
* 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.`
* 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 ### Spelling and Technical Wording
To provide a consistent and high quality documentation, and help users to find the right pages, To provide a consistent and high quality documentation, and help users to find the right pages,
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment