My biggest peeve, is bad indexing.

The docs are there. The information is there, but finding it, is so difficult, that I have often just said "bugger this for a lark," and written my own implementation.

There's two types of docs: The teaching kind, as the article mentions, and the reference kind, for helping folks that already have a start, to find what they need.

I generally do the second. It can be fairly easily generated from inline headerdoc comments, these days, but we still have the issue of indexing, and I still have my work cut out for me, there.

Here's some stuff I wrote about my approach to documentation: https://littlegreenviper.com/leaving-a-legacy/