Our docs are shit and we're bad at teaching | deadSimpleTech— Get new articles delivered to your inbox
Enter your email
Enter your email
Get Updates →
Also send me the monthly newsletter
Our docs are shit and we're bad at teaching<br>Author: Iris Meredith<br>Date published: 2026-05-23<br>I read an article by Ali Alkhatib titled Weeds tend not to grow where they can't take root with some real interest today. In it, Ali argues that if we're to effectively oppose AI and AI initiatives, we can't merely destroy the existing structures: we have to build counter-structures that make the very idea of using AI a bit pointless. AI, in his model, occupies spaces where there's a problem in need of a solution but current solutions are so inadequate that an LLM seems like a good option for solving it: AI merely occupies space that we've left that it could occupy.<br>Simultaneously I've been working on my website a bit of late: in the interests of my LLM research I've been using a coding agent for some tasks but not others and taking copious notes on how it works, what it does and how it's been affecting my psyche. This isn't another one of my "state of the models" pieces (that one will probably come later), but about something I noticed while doing this work: namely that the state of knowledge transfer in tech is awful, or to put it in more techy terms, the documentation is shit. More than anything else, I think this is the main place where we've created space for LLMs to grow in our field.<br>Consider just one task: getting OpenTofu state set up in Gitlab so that my website deploys automatically when I push a tag rather than having to do it manually. This required me to chase down something like four or five separate sources of documentation. First off I need to figure out how to get OpenTofu to store state in the Gitlab backend rather than locally: configuring that requires me to look up the OpenTofu docs to figure out how to configure an HTTP backend and then get, from Gitlab, the appropriate API endpoints, a bunch of credentials and the project ID. These are all documented in different locations and not linked to each other, which given that they're all likely to be used together is a massive oversight. I then have to figure out how to effectively run OpenTofu commands from within Gitlab CI: there are a couple of different ways of doing this, all of them inadequately documented, and the pattern that I eventually settled on (pull the official OpenTofu container from GHCR and do the operations in there) isn't even documented by Gitlab at all. Then there's the question of the Butane config that I need for the VM: that needs to be built and stored as an artifact in yet another step... you see the issue, yes? The complexity of this quickly becomes unreasonable, and learning how to do something when you don't already know how requires you to track down a whole lot of information from a whole slew of often very bad sources.<br>The average quality of documentation available for most tech is abysmal. It's often incomplete, poorly-organised (which is to say that it's organised in ways that don't correspond to how it's likely to be used), leaves out vital information or is just plain unreadable. Even much of the documentation that makes sense in hindsight is often more or less incomprehensible in foresight until you see an example, and step-by-step examples are often absent from the official docs. Even when an example does exist in official docs, it's way simpler than anything you'd ever implement for real, and so useless. You're stuck looking for third-party examples, and when you go searching online for those, you quickly find that there are an awful lot of them and that the vast bulk are terrible. Learning how to do something from documentation, in short, is usually way harder than it needs to be.<br>There's also way too much of it. At a current count, the technologies that run my website currently have 78 different official documentation pages between them, and this isn't for a particularly complex project! Even if I were to write my website in plain HTML and publish it that way (and that would lose a lot of stuff, such as mathematics typesetting and email subscriptions, that's of real value and not just needless complexity), there are still thirty or so documentation pages involved in just deploying that. That is, quite simply, far more material than any person can reasonably ingest even if it's easily digestible and easy to learn from (which, as we've established earlier, is not the case).<br>In this kind of environment, finding any way to get stuff done at all, much less finding a good way of doing it, is almost impossible. Is it any wonder that people resort to LLMs for finding their way through what is, when all's said and done, an unusable morass of poorly-written information? There's a real problem here, and it bears understanding.<br>We're generally shit at teaching<br>The root of the problem is that software engineers and software people...