Why are we still so bad at writing documentation? It’s been a long time since Python demonstrated how good software documentation could and should be. It’s over a decade since Write The Docs started putting on conferences specifically to improve documentation. Heck, Daniele Procida’s lecture on the four types of documentation was in 2017. So why are we still so bad at most of it?
For those who don’t know the Diátaxis model, it breaks documentation down into four categories:
- learning-oriented tutorials
- goal-oriented how-tos
- understanding-oriented discussions
- information-oriented references
That last one is what most people think of as documentation. It’s what prompted the development of Doxygen, leaving us with very little excuse for not creating proper references for our libraries. That said, learning that mylib_enfooify_bar() turns a bar into a foo doesn’t actually add to the sum total of human knowledge, particularly if “foo” and “bar” aren’t explained. I dare say I’ve committed my share of such things; there’s very little a description can add to i2c_read_register() that isn’t pretty obvious from its name and parameters.
I learned to treasure a lot of the other sorts of documentation as a young programmer. SJ Research supplied computer networking kit to schools back in the days when schools were first getting computers of their own, and more than likely were putting the elderly maths teacher in charge of them. What changed my mind about documentation was the company policy that all the engineers had to do technical support part of the time, answering the phone and dealing with the sometimes very strange problems that came in. The third time someone asked me the same question, I went away and wrote the application note that answered it so I didn’t have to do that again.
While I have plenty to say about what’s usually missing from documentation collections, this article is supposed to be about why we don’t write more of it. I don’t think it’s because programmers don’t see the need for it. I’m sure we’ve all been bitten by the lack of the right documentation more than once, and most of us aren’t sociopaths and don’t really wish that sort of problem on other people.
I think that there are two basic reasons. The first is that most software engineers aren’t also creative writers. We didn’t really learn how to write the essays that are what you need for tutorials and how-tos, and sometimes even the couple of paragraphs to explain what an obscure function is doing can be a challenge. Getting up the enthusiasm to explain what a package does is often rather hard.
The second reason compounds the first; it’s a cost. Aside from design documents, a lot of documentation tends to get written towards the end of a project. Once the project is (mostly) code complete (and possibly even tested), spending engineer time writing documentation doesn’t have an immediate benefit. It’s an investment in future development and maintenance, but by this stage everyone is tired and wants to move on to the next project, and the further up the management tree you go the less obvious this investment is.
This doesn’t apply to user documentation. Sales and marketing people are usually keenly aware that it’s good if users know how to use what they’ve bought from you, so that kind of documentation gets prioritised. In a large enough company, it will be written by professional documenters who are creative writers and have the advantage of not having written the code.
Somehow we engineers need to make it clearer to ourselves what the cost of not writing the rest of the project documentation is. Just because it’s a cost that you or I personally may not pay doesn’t mean that it isn’t paid, and whoever comes after us will not thank us for it.
Is this something that AI can help us with? I haven’t looked into this at all, but my gut feeling is that it could within limits. AI should be really good at reference documentation and might create decent tutorials and how-tos, but I would expect it to struggle with understanding-oriented documentation. Aside from the whole issue of what “understanding” is, I don’t think there are a lot of good examples of that sort of documentation to teach it from right now. Has anyone out there tried using AI as a technical documentation generator? How have you fared?