Beyond spell checking - what else can we check automatically?




Writing documentation is hard, and spotting errors in that documentation is harder. Luckily, if we're working in a docs-as-code environment, we can apply some of the techniques that programmers have been using for a long time, in particular linting, the automated checking for common errors or stylistic problems.

In this talk, I shall go through some of the types of check it is possible to make, including spell checking (it's still important), suggesting replacements for words/phrases (multi-cloud instead of multicloud), "if this then that" rules (remember to expand an acronym on first use) and targeting checks more closely using simple NLP (Natural Language Processing)

I'll cover the use of pre-prepared styles, and I'll give some consideration as to how linting can be "plumbed in" to the review process.

At the end I'll demonstrate how to implement some of these techniques, using the example of Aiven's open source developer documentation. I'll make sure to include my favourite check, for the correct usage of ® on product names.

  • Conference: Write the Docs Prague
  • Year: 2022

About the speaker