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.