Howto: Writing good documentation
| Authors |
|
| Last Updated | 10/12/2025, 12:48:54 PM |
| Last Author | Kai Berszin |
Scope
This articles tries it's hands on quite a difficult topic: How to write good documentation. It follows Divido's Grand Unified Theory of Documentations and proposes a standard structure for articles.
Documentation types
The documentation is differentiated into four categories, each taylored for different use cases.
| Documentation types | Tutorials | How-to guides | Reference | Explanation |
|---|---|---|---|---|
| oriented to | learning | a goal | information | understanding |
| must | allow the newcomer to get started | show how to solve a specific problem | describe the machinery | explain |
| its form | a lesson | a series of steps | dry description | discursive explanation |
| analogy | teaching a small child how to cook | a recipe in a cookery book | a reference encyclopedia article | an article on culinary social history |
In SAGE we are mostly concerned with the last two types of documentation Reference and Explanation.
Reference
Reference type of documents should only give a high level overview of the design decicions made, describing what has done and providing facts.
It should not try to give justifications for why a specific desicion was made, for this use an Explanation.
This document should be quick to read and understandable also from people from different expertise backgrounds.
An explaination document should be linked to provide a deeper insight into the design decision.
The following ECSS type documents can be seen as Reference Documents:
| ECSS Documentation Type | Purpose |
|---|---|
| - System Requirements Document (SRD) - Interface Control Document (ICD) - Technical Review Reports (SRR, PDR, CDR, etc.) - Quality Assurance Plan (QAP) | Provides authoritative and detailed specifications, requirements, and review outcomes for engineers and managers. |
Example
The OBC PCB is described in a high level manner.
Physical dimensions are given, the various connections are described (connector type, voltage level, ...).
The most important electrical components are named, i.e. MCU type, memory type, etc.
A complete list of parts can be given in a seperate reference or explanation document, depending on the scope of detail (i.e. if just a list create a reference, if justifying each single part create a explanation)
Specifications for create PCB designs for space applications.
What kind of materials may be used?
What kind of solder is to be used?
Explanation
Explanation type of documents, gives justification for specific design descicions and shows trade-off studies.
The following ECSS type documents can be seen as Explanation Documents:
| ECSS Documentation Type | Purpose |
|---|---|
| - System Design Document (SDD) - Failure Modes, Effects, and Criticality Analysis (FMECA) | Explains system design choices, potential failure risks. |
Example
Specific Design Choices of the OBC PCB are explained. Why was the STM32H7 choosen over the STM32F4? What is the power dissipation of the MCU and what is done to prevent overheating?
Tutorials and How-Tos
These documents will be a minor part of the SAGE documentation but is still important as well.
Tutorials and How-Tos mainly include processes.
i.e.
- How to onboard a new Person?
- How to use the EOS software?
- How to create a PCB design for Space.
How-Tos can reference Reference documents i.e. The How to create a PCB design for Space should reference the Specifications for create PCB designs for space applications reference document.
Structure
Basic Blocks
A document should start with a Scope block, giving a brief overview of what is described in any given document.
Document split
Documents should be split in multiple pages in a logical manner.
A logical split is the physical distribution of tasks.
Each person working on a specific problem should be responsible for an own reference page describing their work.
Basic Tips
- Define the intended audience (general team or field expert)
- Adjust technical depth accordingly (basic concepts for general documents, advanced details for experts).
- Assume a basic technical understanding (not: The battery provides power to the system.)
- Use clear headings, bullet points, and short paragraphs for readability.
- Avoid unnecessary details — stick to what’s essential.
- Use diagrams and flowcharts for complex concepts.
- Avoid filler words like “basically,” “just,” or “simply”—be direct and specific.
- Use consistent terminology across the document (e.g., don’t switch between "config" and "configuration").