How to document in a comprehensible way
The goal of this page is to get a team-wide understanding of what might be important for writing comprehensible documents for others, including non team-members. Take the following with a grain of salt and try to put yourself into the shoes of a unknowing reader of the document you are writing.
- include what the goal of this page is
- state the context of this page
- ....just a broad overview
- ....an explanation of configuration
- ....after this read you should be able to do....
- include what knowledge might be necessary to comprehend the content, add links for that lead to the required knowledge source
- keep the documentation as short as possible but as detailed as needed
- try to avoid block text and Prosa
- pictures, figures or other visualizations might tell more than words and in a more precise manor
- it describes the content in a summarizing way.
- uses keywords which correlate with the topic you would look for this content
- e.g. guides should contain "guide" or "how to"
- further details about a topic or explanation "Details" and "Explanation" when applicable
- Guides usually state first what it will help you to accomplish then the required context and steps
- it will help to guide the reader
- use ordered lists for each step one
- make use of
code snippets - include the relative path for commands if applicable
- use
code snippetsrather than row information cause we have no row markings - split the code if you want to explain a certain row in more detail or have an extra paragraph explaining with
code snippets - state if code is generated
- state if code parts are necessary predefined parts required by other components, referencing those components, if applicable