For those who are new to my blog, hi, I my name is Tony and I am a technical writer. More specifically, I am a technical writer with 25 years’ experience in the role, and have plied this trade at all levels, from writing illustration-heavy instructions for self-checkout robot supervisors working in grocery stores to system administrators tasked with rebuilding market-trading systems from scratch in the event of a major disaster such as an earthquake — covering both hardware and software. I’ve written docs for distribution in printed manuals, virtually-printed manuals (you know, Acrobat format), and online help formats. I’ve implemented XML-DITA based complex help infrastructure for companies. I’ve also created and maintained web sites since the web became something accessible to everyone in the mid-90s.
I’ve also been looking for a job for a year now. Sadly the only “success” I’ve had was to get a technical support job for which I had not applied, but was contacted directly by the manager, and I’ve been spending the last 7 months wishing I’d said no to that one for so many reasons, but that’s a story for another day. Let’s just say that I have learned to look on unsolicited job offers with suspicion, maybe a little late, but it’s probably better than if I had never abandoned the “let’s not look a gift horse in the mouth” attitude.
The simple fact is that AI has taken a huge bite out of the numbers of jobs in the software field. I’ve been laid off several times, and more than once jumped at surprise job opportunities which turned out to be nightmares I ended up bitterly regretting. The point is, at many points in my career I have looked for new employment. As with the craft of technical writing, I have lots of experience in that. And yes, there are far, far fewer job offers in the field than there used to be. This is a manifold problem — and the rise of generative AI has had a role to play in most of it.
- Many companies seem to think that the nature of AI as a “large language model”, and the fact that it can generate intelligible text, means that you don’t need writers
- Companies have been laying off hundreds of thousands of IT workers in many different functions thinking that AI can do those jobs, resulting in a glut of available IT workers with industry experience and qualifications
- AI companies right now are soaking up capital that would otherwise be going to fund profitable companies and sinking that money into an endless money pit.
Now, there’s not much that can be done about that third factor. Right now the only thing money managers are seeing is that “market gains” — little more than enormous bets — are favoring AI companies for investment money. In a world where the stock markets have become little more than speculative betting parlors, it’s just something we have to live with.
However, the technical writing market is, I would argue, unfairly paying the price for AI’s unrealized — and in my view unrealizable — promises, and falling victim to what’s known as the doorman fallacy. Note that the doorman doesn’t have to be a man, but that’s how the fallacy is widely known at this time.
To put it simply, the doorman fallacy describes the pitfall of reducing a role to only its most obvious characteristics. Why would you pay someone to be a doorman? On the surface, it doesn’t make any sense to do that. People can open their own doors, they already do that every day in their homes. Why not just install a revolving door that anyone can walk through without any effort, or an automatic door?
The fallacy here is that a doorman provides a service that goes beyond simple ingress and egress from a building. The mere presence of the doorman shows that there is someone there paying attention to the people who enter and exit the place, and to the general environment of the building. If you’re someone who lives there, this provides a certain level of comfort, not just in not having to open the door yourself, but in the sense of knowing that if something unusual is happening, this person can tell you about it. In the classic sense, the doorman can also tell you about other places in the neighborhood, such as where to go for lunch. They can also receive packages for you. If there’s a fire happening in the building, they may be the first person to know about it and contact the fire department.
And by getting rid of the doorman, one simply abandons providing all those services. People living in New York City know what that’s like, and that’s why apartments in “doorman buildings” rent at a premium.
Opening doors is just a small part of the doorman’s job.
Getting rid of technical writers because “the LLM can write” is to fall into that trap. Actually writing the docs is only a small part of what a technical writer does. Most of the job, for any technical writer position, consists of knowing the product inside and out.
An LLM may be able to take a web app, go through it, and tell you what each option in each UI element does, but it cannot tell users how to execute the tasks they want to use the software to accomplish. That is a technical writer’s real job. Yes, “writing the docs” may technically be a description of what we do, but in order to get that done you need to integrate a lot of knowledge, including (but not limited to):
- knowing the audience for which the docs are written (the most essential part, I would argue)
- knowing why the audience needs to use the product, what they hope to accomplish with it
- knowing the ins and outs of the product
- testing the product from a user-acceptance point of view
- passing feedback to the development team as to what works and what doesn’t — not just bug reporting, but is the product putting obstacles in the user’s way
- organizing this knowledge into a logical and natural pattern for the user for the online help
- identifying areas where the user may need more context-sensitive guidance
- organizing the knowledge of the product in ways that will provide the most practical way for the organization to keep said knowledge so that it may be used by product managers, project managers and developers
By getting rid of technical writers companies are largely abandoning knowledge about their own products, their users, and how to best serve their own needs in the future.
Likewise there is an idea among tech companies that the technical writer’s role can be filled by developers themselves. This is another trap. Developers in this day and age tend to work on a specific feature, or sometimes a sub-feature, and once that one “atomic” piece is complete move on to another feature. Rarely does a developer have a good overall sense of what the product as a whole is supposed to do, except maybe in the case of senior devs within a company who — and they will freely tell you this — have little time for the docs, except for API documentation where they more often than not end up being both the consumers as well as the producers. But again, APIs are domain-specific, and rarely cover the full functionality of a software product.
The other aspect of this is that developers look at a software product as something they make, and not something they use from end-to-end. Something may seem very obvious to a developer but require explanation to a layman who is just trying to use the product to accomplish a task that’s entirely foreign to them. I’ve met many developers who are absolutely brilliant at what they do, but once they step outside that very delimited discipline they are simply at a loss for words and engage in behavior that strikes non-developers as bizarre and irrational. The same is often said of (for example) university professors and people with PhDs. They don’t give doctorates to stupid people, that’s just a fact. However the same thinking that gives rise to industry-leading developers and thinkers leads to people with extremely deep knowledge in one particular area of knowledge to the detriment of other areas, including many that are just common sense to most people. As I said I’ve worked in the software industry long enough to know how true that is.
And this brings us to the question of what role artificial intelligence has to play in the technical writing process. And I would argue that I just don’t see much there. Technical writing, at least in the software industry, is about taking a product that was written by people, and making it easier to use by other, completely different people. And that’s why you need people in technical writing positions.
Yes, there are contributions that can be made, largely in the area of analytics. In a world where documentation is mostly distributed online, it’s very useful to be able to identify which areas of the documentation are being consulted, how much time users are spending on those areas, and which areas are barely if ever looked at. But I would argue that consulting with technical support would yield greater benefits. See what subjects users need to consult technical support about — it’s not just bugs. Sometimes the documentation can use more conceptual information before jumping into individual tasks. Sometimes a feature may have been updated without letting the documentation team know about it. That happens, especially with distributed teams. And technical support teams tend to have far better analytics already in place than documentation teams, because that’s a large part of their key performance indicators (KPIs) in a way that it’s just never been for documentation teams. But there’s a certain role there.
However when it comes to the core tasks of technical writing, I just don’t see much of a role for generative artificial intelligence.
Does that mean I’m against AI altogether? I’m not against the concept. I find it useful as an agent that can handle the coding part of development. Why? Because coding is a discipline that’s very tightly delimited. And by “coding” I mean in the strictest sense — turning algorithms into code, and doing basic testing on the resulting code to ensure that it works. The algorithm still needs to be spelled out by the user for AI coding to be effective. And the code needs to be read and reviewed by a human to make sure it doesn’t have a ton of side effects. It’s also proving to be a lot more expensive than what its chief sales people have been clamoring. When a company releases a new technology, it’s looking to monetize. That’s literally the only role of a corporation. Look out for the shareholders.
AI has its uses. Thinking those uses include technical writing is a mistake.