Technical writing in the age of AI

(Inspiration for this post was The Safest Job from AI may be Writing)

Replacing technical writers with AI agents writing documentation partially fails because there is no equivalent to software tests for documentation. There are some documentation testing frameworks, e.g. Doc Detective, and you can test parts of your documentation, but it’s not equivalent to code tests, which has more extensive testing and different testing types (unit tests, integration tests, regression tests).

You can generate slop code and test the outputs, and if the outputs are good, the code works and is therefore “good”, however sloppy it might otherwise be. (In domains where scalability, speed of execution, correctness in specific edge cases, and other such attributes are important, the code may not work because you cannot write a test for some of these requirements.) You can’t (fully) do the same thing with docs. You generate slop docs and…? Are they correct? Do they work, for any definition of “work”? Nobody knows. To check, someone would have to go through the steps and fail/succeed, at which point you’re doing technical writing.

Moreover, experiencing documentation means reading it, regardless of whether or not the reader achieves some objective. This is different from code: an end user interacts with code through an interface (a graphical one, or an API/contract) and therefore doesn’t necessarily need to interact with the logic that drives the mechanism of the code. They just need to send an input and receive an output. Even sloppy code is acceptable to the end user if it returns the desired result.

Compare that to documentation where the end user is required to read it: reading is interacting, the text of the documentation is the API. Writing style, conciseness, having a model of the reader, and so on, are all more important for documentation than for code, even if in the end, the reader accomplishes their goal regardless of the sloppiness or non-sloppiness of the documentation.

Finally, documentation carries with itself an implicit promise that a) there is someone who understands the subject matter, the issues, and how they were solved, and b) that this someone has decided to put their thoughts on paper teaching the reader and explaining to them different aspects of the problem-space and the solutions, and how one can use the created software artifacts to resolve the problems.

However, I concede that this last reason would also apply to code, and that it doesn’t really apply to the documentation in practice, and that this implicit promise has been broken more than kept. This is a standard of professionalism of yore, something that no longer applies in many cases, an erosion of trust and culture, at least to the extent that there ever was a time when professionals took pride in their craft and did in fact take part in this social contract of documentation.

And if I am being equally pragmatic, then this erosion extends to style, clarity, conciseness, all attributes listed in my 2nd point. If the end user ends up getting to the same result while reading bad prose in the same way as an end user who got to that result while reading good prose, good prose is somewhat irrelevant, though not fully irrelevant. It’s the same kind of irrelevance that happens when you have cringe AI-generated visuals. For some businesses, it really may be irrelevant, their relevant metrics will go up despite having bad taste. For others, there may be a financial cost associated with bad taste, and with poor prose.

There are also different aspects of (technical) writing. If you take the standard Diataxis division, AI is pretty good at building references. You can probably fully automate that and have your technical writers forget that they ever worked with code annotations or API reference generation. When it comes to how-to guides, that depends on the domain. Current agents are good at writing quick start guides for e.g. performing an initial API call, stuff like that. The more subject matter expertise required for a how-to guide, the worse agents will perform. For tutorials, I’m not sure, I think that agents work well for building introductions but given that they don’t really have a developed taste or have a model of the reader in their mind, I am skeptical of their success in the tutorial quadrant. Finally, in the explanation quadrant I think that they are very bad unless there’s a written record of trial and error during the design stage. Explanations are basically architectural records and are a mix of a bunch of things, so I guess that if an agent designed a thing from scratch, did its own iteration (trial and error), and saved all of its thinking traces somewhere, then I could see good explanations coming from agents. Otherwise they’d be inventing, and you don’t want any inventions in an explanation, you want someone to give you an overview of the problem space and how it was ultimately solved.

And all that is for technical writing in one of the four Diataxis quadrants. There’s also other technical or technical-adjacent writing. For example, explaining a design philosophy, or explaining a subject where the author collected expertise through a number of years, where there’s a lot of tacit knowledge that hasn’t been fully integrated in an agent’s training data. Or the genre of takes, where you basically never want to read an agent’s take on anything, as the whole point is to read the opinion of other humans, and rely on agents to be tools to perform actions.