Pascal once wrote in apology "If I had more time, I would have written a shorter letter". Be exactly as detailed as necessary and no longer.
I think this "documentation framework" has helped me a lot to write precise docs and how to structure everything regardless of the platform
* The Bash manpage [1]
* FreeBSD docs, in general — the "base system" implementation and
documentation go hand-in-hand. If there's missing docs for a
built-in tool, that's treated as a bug.
* SQLite's documentation of the SQL language syntax [2]
[1] https://linux.die.net/man/1/bash
[2] https://www.sqlite.org/lang_select.htmlI didn’t read the article so much as saying to grind through the dirty work, but to look at the existence of dirty work as a chance to (a) fix someone’s pain, preferably a lot of someones, (b) level-up your organization’s abilities in an area. At a job in the early 00s we had zero developer-facing documentation, so everything was an oral history project… this was awful, especially after we turned over a bunch of eng staff. I set up a couple of very simple systems for docs, and - this is the part that is the grind - started writing stuff down every time I had to answer a question from a coworker. It didn’t take long before I was mostly just pointing people to the doc system, and then eventually other people started adding to it. At that point it snowballs and basically the doc problem is “solved”. (There’s still work, but there’s a system in place that reduces the overall effort required.)
I don’t really disagree with you that docs are sometimes just a thankless grind, but I think the point is to find something that is dirty work but also has a really high and visible impact.