*************
Writing Style
*************

The writing style across all topic pages should feel:

* friendly,
* honest,
* humble,
* positive,
* professional,
* and encouraging.

General Guidelines
==================

* Use vocabulary that is easy to understand for an international audience.
  Many readers are not native English speakers, therefore avoid unnecessarily complex wording.

* Assume that readers are experienced software developers.
  You can rely on basic knowledge about software architecture, design patterns, algorithms, and programming
  terminology.
  You can *not* rely on knowledge about the described topic, because this is the reason a person reads that page.

* Add relevant background knowledge when it helps readers understand *why* a design or API behaves in a certain way.

  Examples include:

  * why a specific algorithm was chosen,
  * why a certain API design improves safety,
  * or why a feature behaves differently from similar libraries.

* Write in an engaging and direct style.
  Always address the reader personally whenever appropriate because this improves readability and learning efficiency.

* Prefer practical explanations over abstract descriptions.
  Readers should quickly understand how they can apply a concept in their own projects.

Topic Pages
-----------

* The text should be a good read that readers enjoy to read. It should not feel like a list of instructions.
  It should feel like a good book about an interesting topic, motivating developers to read and learn.