General documentation tips

1. Golden Rules of Documentation
   1. Documentation Must be Easy to Understand (#1)
   2. Documentation Must be Easy to Use (#2)
   3. Documentation Must be Specific and Comprehensible (#3)
   4. Documentation must provide meaningful value (#4)

The following section provides easy-to-apply and useful tips on how to effectively handle documentation tasks. These tips are not limited to technical documentation; they can be applied universally to any documentation task.

Golden Rules of Documentation

Documentation Must be Easy to Understand (#1)

• Write in active form and use short sentences.
• Use language that is easy to understand and straightforward.
• Keep your writing concise and do not overwhelm the reader with too many details.
• Only go into detail if it adds value for the target audience.
• Visualize information using tables and graphics.

Documentation Must be Easy to Use (#2)

• Write in a target group-oriented manner and use domain-specific technical language.
• Use a solution-oriented writing style that supports the reader in completing their tasks.
• Use modern documentation tools such as hyperlinks for semantic context navigation or reusable text containers.
• Ensure easy findability and easy access to the documentation for the target group.
• When using information and images, pay attention to avoiding data protection or compliance violations.
• Use documentation templates and provide reference documentation.
• Delete empty chapters and template text that originate from a template document (these will become obsolete after the next update to the template, so you no longer need them!)

Documentation Must be Specific and Comprehensible (#3)

• Depending on the target group and use, separate the documentation into different documentation artifacts, such as administration manual, requirements documents, technical documentation, etc.
• Use a version control system for the documentation artifacts to that changes made to the documentation can be easily tracked via the version history.

Documentation must provide meaningful value (#4)

• The documentation benefit must be greater than the costs of creating the document and keeping it up to date.
• Involve the authors and the readers for whom the documentation is written in the process of defining the documentation guidelines.