Beyond spell checking - what else can we check automatically?¶
Sketchnote
Description
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
