Brussels / 3 & 4 February 2024


Style as code: Using open source tooling to codify technical documentation style

Defining style as code lets tools do the hard work of remembering the style and gives technical writers and engineers the feedback they need to produce better documentation.

Reading good documentation is deceptively easy, and writing good documentation which is easy to read is hard. Both native and non-native English speakers find communicating useful and clear information in technical documentation is a challenge. Style guides from Google, Microsoft, and many others exist, but those are huge amounts of documentation themselves and are very difficult to memorize.

In this presentation, we will cover:

  • Why consistent style is valuable in improving inclusivity, readability, and clarity of documentation
  • The challenges of ensuring consistency, including managing exceptions and defining priorities of style rules.
  • Creating clear explanations so that writers feel empowered with knowledge rather than berated with pedantry
  • Demonstrating open source tooling that solves these challenges using Vale, a configurable, open source tool, an extensible rule set, support for many markup languages, and editor and CI integrations.

We'll also demonstrate:

  • Getting started using existing rulesets
  • Specific rules written and open source by Grafana
  • Configuring Vale for a project
  • Introducing linting incrementally with reviewdog


Photo of Jack Baldry Jack Baldry