ADR 002 — Documentation Writing Style
Status: proposed
Decision makers: Support and Care Dev Team
Date: 2026-xx-xx
Related issues: GitHub #56
Context and Problem Description
As part of the "Getting started" documentation effort, we have to decide in which writing style we want to write our documentation. We are deciding it in this context because "Getting started" documentation is our starting point.
Considered Options
- Informal Style
- Formal Style
- Mix of both styles
Decision
Formal Style
We want to write the documentation in a formal style. We expect that the content is read more professionally, and it helps us to focus on the topic. For the reader, we expect that the text is easier to read.
Positive Consequences
- clearer text
- more focus on the content; it avoids "noise"
Negative Consequences
- harder to write for the author
- needs more time
Considered Options
Informal Style
In this context informal style means that an article is written like "talking to the reader", e.g. "This page walks you through"
- Good: Easier to write in a motivating way
- Bad: Authors tend to "written like spoken", so that context and accuracy can be lost.
Formal Style
In this context, formal style means that an article is based on established conventions and avoids informality, ambiguity, and personal bias, e.g. "This guide covers the following"
- Good: Focus on the topic
- Good: Clearer for the reader
- Bad: Requires more focus while writing to not drift into informal style
Mix of both styles
In some cases, it can be useful to mix both styles. For example, on a landing page, informal style could be more motivating but in the installation chapter a formal style helps to have clear step-by-step instruction
- Good: You have a choise to choose the right style for the right situation
- Bad: More space for dicussion in which situation which style is useful