Its Not a Great Time to Be a Docs Enjoyer
I didn’t always enjoy reading docs or manuals for software that I was using. Despite the constant chant to RTFM in forums, I used to get by through tutorials and skimming just enough docs to do the things that I wanted. I nonethless appreciated that docs were an authoritative source which could always diambiguate things. Though as time went on my appreciation for good documentation grew and eventually solidified into making me one of those people who tries to read the docs completely if possible or at least skims it completely. (To be clear I don’t do it all the time and for all software that would simply be infeasible). I don’t exactly know when this transition happened but it must be relatively recent and to my great misfortune this seems to have coincided with a deluge of bad software documentation Thoughout this article I use docs, manuals, wiki’s interchangable and I understand that they are different but the general malaise that I’m talking about doesn’t differentiate between them .
There were always bad docs. Nix docs is a good example. Nix is probably the software with the highest ratio of value of the software to quality of the docs. But for mature software you’d often either have relatively decent first party docs or at the very least community maintained high quality docs and wiki’s (for example ArchWiki). A recent example of pretty good docs that I at least skimmed relatively completely was the Typst docs. If you go through the docs end to end, you come out of it knowing everything that the software can do and can feel relatively confident in typesetting any document that is possible with Typst. Sure you might have to revisit the reference sections multiple times during implementation, but you’d be less surprised of edge cases and more cognizant of it’s entire feature set.
Previously for a relatively niche software, documentation was either scarce or unavailable and you had to rely on forums, blog posts written by early adopters, experiment with it yourself stumbling through features and bugs alike (the bugs would often be due to using it in ways that the developer never intended) or straight up read the source code if you were adventurous. The problem now is the opposite, there is a glut of documentation with reams of pages for a simple product that was just released with a mishmash of features.
It’s not always easy to pinpoint why exactly something is bad. You can look at a bad design and know it’s a bad design, same thing with bad typefaces, but you’d be hard pressed to pinpoint what exactly is wrong. Articulating why something is bad requires you to be relatively proficient in that field. As someone not proficient in writing docs, I don’t know why exactly a lot of recent docs are terrible. Maybe it’s their grating use of mechanically generated language, maybe it’s that they are not following Diátaxis format for docs, I don’t know. But I do know that a lot of documentation for the software coming out except being voluminous is not great.
Maybe the intention is that you as the end user is no longer supposed to read the docs, but rather ask your agent to read through the docs and surface the right information when you stumble on something unknown. Because it sure looks like the writing can only be parsed by machines that wrote it. This certainly seems to track the dream of product designers who look at docs as a failing of the product.
It is a well known idea that users don’t want to or simply don’t read the docs. As such product designers have spent years trying to build features which are obvious and which try to hide complexity and have invented patterns like progressive disclosures. The outcome of all of these is the death of software with power user features and cutomizability I should point out I'm not against design which tries to make things simple and obvious, but rather against design which are paternalistic . It’s undeniable that software which assumes no knowledge from the user has to do the heavy lifting and provide context while performing the action. Though this might be a good thing for infrequent tasks, but for frequent tasks the additional context only gets in the way. Good design avoids this by linking the user to a documentation for a feature, after introducting the feature. Software that relies on heavy contextual documentation also can’t be customized well since the documentation and the feature are bundled together and a new feature which could potentially be built by composing other features can’t be exposed to the user without building custom documentation for the compsosed feature.
LLM’s might be writing software at ever greater speed, but if the end user of those software is supposed to be humans (and let’s be clear all software however abstract eventually serves a human need, k8s exists to orchestrate nodes so that an end user can eventually access a web page on one of those nodes), then we need good documentation to go along with it. I think the lack of good documentation is particularly egregious for newer software which are supposedly built for developers, people who are supposed to be power users. I think this is unfortunate especially for newer tools which seem powerful but there is no way to know definitively what all they can do, without trawling through the source code which even the developer might not have completely read.
Technical writing is an actual field with dedicated people who spend a lot of time thinking about how to make technical material digestable. A lot of good docs are written by people who have either formal or informal experience with technical writing. They understand what trips people up, how to inform users and not overwhelm them while also being complete. Like a lot of things, you never appreciate what you’re missing untill you are confronted with a situation without that thing. For me atleast my appreciation for good docs and technical writers has gone up with the rise of slop-docs.