# Our docs are shit and we're bad at teaching

> Source: <https://deadsimpletech.com/blog/docs-shit-bad-at-teaching>
> Published: 2026-06-16 02:28:06+00:00

I read an article by Ali Alkhatib titled [Weeds tend not to grow where they can't take root](https://ali-alkhatib.com/blog/weeding-out-ai) 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.

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.

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.

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.

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).

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.

## We're generally shit at teaching

The root of the problem is that software engineers and software people tend to be pretty awful teachers. While there are a few notable exceptions, as a general rule we tend to be socially maladjusted, ill-tempered, lacking in the perspective-taking skills needed to understand what a new learner will probably find confusing or what people need to know to start being productive quickly and arrogant enough that we think none of the other things are an issue. For someone new to all of this, the experience is roughly akin to a form of slow-motion hazing: we don't explain anything properly, we get frustrated when they ask perfectly reasonable questions as though they should have known the answer already, and as those of you familiar with StackOverflow back in the day know, this often drifts into outright abuse and put-downs. None of this is necessary or even good for learning, and the overall effect of it is just that only the people willing to push through all this shit end up learning. Naturally, they look, demographically and personality-wise, much like the people already in the industry and by the time they've earned their place as a tech person, they're largely conditioned to repeat the experience for the new blood coming in.

Even without that lot of shit, we mostly don't put any effort into learning how to teach effectively or how people learn. This is a whole field that teachers spend a lot of time learning (both my parents being teachers later in life, I was lucky enough to pick up quite a bit while I was growing up), and while I hardly expect us all to do a full teaching degree, a bit of knowledge as to how people learn would not kill us. If you look at a good course or a textbook, for example, a large part of the text is made up of not just theoretical facts and blather, but of *examples*. And it's not just one example: we start with a simple example to build a baseline of understanding, we have people do an exercise or two to confirm that they understand the example and can reproduce it themselves, and then we *build on it* with a more complex example. It's an iterative process, and coming up with good examples and exercises is a skill in itself.

Of course, it makes sense that almost none of us really bother to develop teaching skills: they're hardly rewarded in the marketplace. Being good at teaching new developers, or even experienced developers that need to get up-to-speed on your stack, is seen as feminine, caring labour (because, of course, everything is gender). If you're good at teaching, enjoy it and put effort into it, you're seen as being less good at the hard technical work of pushing yet another shitty feature than none of your users want. And of course, when you're dedicating energy to helping new people become productive with your stack, you're not pushing shitty features yourself. Obviously, then, at promotion time the person who's most likely to get the promotion was the one pushing the features. And thus, in yet another way we disincentivise people from learning how to teach or putting the effort in, and the fact that tech and the industry are terrible at teaching remains the case.

If we were working at some other field, this would be awful but it might not be too much of an issue. Unfortunately, we work in an industry where teaching and knowledge transfer are about as integral to the job as they can get. To point at just the most obvious example, and the one that we discussed at the very start of this article, documentation is a teaching resource. Whatever else it might be, in reality the practical goal of documentation is to teach someone new to technology enough about the system that they can contribute to developing it without adding technical debt: it is first and foremost a teaching document. API schemas and documentation for libraries are very similar; their first job is to *teach people how to use the technology in question*.

Given the proliferation of technologies that we currently deal with even in relatively simple projects, this means that teaching and learning is a core function of a software engineer's job. While management might well see the job as being shipping features, in practice this is a by-product of teaching and learning: the goal of an engineer is to know the system, the technology and the deployment well enough that they're able to ship a feature. Most of the work that goes into shipping a feature is *precisely* teaching and learning. If we as software engineers are bad at teaching, then, we are definitionally *bad at our jobs*. And so the bulk of software engineering workers at the moment are bad engineers, with the people who could be the really good engineers being pushed to the margins or out of the field entirely. This explains much about our industry.

And so now we come back to the massive proliferation of technologies that even simple projects rely on, all with their own knowledge base and all of which need an independent learning effort to get done. We tend to understand the major cost of this as being in the form of supply chain threats, security and the complexity that comes from dependencies, and while this has a lot of truth to it, it isn't quite right. The major cost of a new technology is a teaching and learning cost: each engineer using a technology has to be able to both learn how to use it in some depth, including all the idiosyncrasies that come with it, and then has to be able to pass it on to other people. And because all of these technologies interact with each other, the amount that you have to teach and learn scales exponentially with the amount of technologies involved because, of course, you have to learn the adaptors between the technologies too.

In a situation where we were good at teaching and understood that software is first-and-foremost a discipline of knowledge transfer, we would be highly unlikely to have developed technology in this way in the first place. We would have developed our technology such that at every step we minimise the amount that a new engineer has to learn and write our documentation such that it is as easy as possible to learn how to do the thing. But us software engineers are bad at our jobs, so here we are.

## The mess we're in

The outcome is obvious: when there's a clear need for people to learn but almost everyone who could teach ranges from "kinda bad at teaching" to "absolutely awful" and the official ways we offer to learn it are incomprehensible, basically unsearchable and incomplete, the space is wide open for grifters and snake oil salesmen to move in. The most innocuous of these is probably the genre of Medium blogs written by junior engineers trying to get attention by teaching people how to do things that the official docs for technologies do not do very well. It's probably healthy for junior engineers to do this to an extent: you learn best by teaching, after all, and it's a relatively harmless way to build a profile, even when the quality of the advice is distinctly mixed. In the absence of good, authoritative teaching content, though, these blogs tend to fill the blanks and that's not always a good thing: they often contain outdated patterns, dodgy security practices and a whole bundle of other things that you don't want new engineers to be learning.

More perniciously, this absence of good teaching material allows for the creation of unbelievable amounts of SEO slop. If you're a less-than-reputable bootcamp, consultancy or SaaS company, after all, people searching for documentation for a lot of these stack elements represent a *great* opportunity to hawk your wares: not to be too cynical, but I'm pretty sure this is a large part of Vercel's marketing strategy, for example. This can be LLM-generated slop or entirely manually generated slop: the effect is much the same, and in the worst cases can extend to entire parallel documentation sites (Neon does this for PostgreSQL, for instance). The quality again varies: the good stuff is pretty decent, the worst of it is clearly written by people who just don't give a shit. Even the good ones leave a bad taste in the mouth though: people deserve to be able to learn without being pushed into buying something, after all, and even the most well-meaning of these providers have an obvious incentive to keep you dependent on their products.

For a senior engineer or someone generally knowledgeable, we have the skills to wade through all of this, but for someone who's just starting to learn, this is a pretty impossible position: the field is full of crap and a lot of the stuff that's *less crap* is actively trying to exploit you. If the person's lucky, they'll have an engineer that's good at teaching in their corner, but as we've already established, those are kind of rare: the average new engineer will struggle to find a good mentor. In that situation, they're probably going to learn badly, or worse, not learn at all: the amount of content that has to be learned, and the difficulty inherent in finding the actually worthwhile resources in the mess is basically insurmountable. And even I struggle with this a lot of the time: it's simply unreasonable for a single person to understand everything that goes into even a fairly simple website in depth.

LLMs are growing in this space. Whatever else they're doing, they at least allow an engineer to have some semblance of understanding everything that's going on in their stack, or at least working on it. They can search documentation (or throw up stuff from their corpus) and give an answer that, while suboptimal, is probably still better than what anyone less than a senior engineer with a full week to research the best solution could do (and of course, who has time to spend a solid week on research these days?). They can help people understand the codebase that they're working with and potentially even reduce dependence on tools if you ask them the right thing (if you know what PostgreSQL is capable of, you might ask an LLM to do certain things in PostgreSQL rather than adding another dependency or buying another SaaS and that might well be the correct engineering decision to make). And they at least give you the feeling that you might have a chance of keeping the whole codebase within limits that you can understand rather than having to wrangle unbearable quantities of documentation.

Are LLMs using way too many resources? Yes. Are they an expensive, questionably-moral and unreliable way to solve these problems? Also yes. But are people going to keep using them unless we as an industry can get our act together and get the industry to a point where you can be productive with a relatively small number of technologies, all of which have high-quality documentation that you can actually learn from? You aren't going to believe this, but the answer to this is also yes. We need to write better documentation that people can actually learn from, which means prioritising people in industry who can teach well, and we need to reduce the number of technologies that go into a simple project to the point where the amount of documentation that you need to know to be able to work on a project effectively is something manageable.

LLM technology is shitty. It will remain shitty. But unless we as an industry can admit to ourselves that we are bad at teaching, that being bad at teaching means that we're bad at our jobs and work to change that in meaningful ways, we probably more or less deserve what we've got coming to us.

Much of my income (which I use to pay for rent, bills and food) comes from my writing, including both criticism of this kind and learning resources, If you're interested in there being more good learning resources out there, please set up a regular donation, or make a one-off one! Every little bit helps, and I am deeply grateful for all of it.

Support independent writing →

*I might be an odd kind of engineer living out here on the margins, but I am a very good teacher. If you'd like to learn engineering soft skills from me, check out the link!*