Technical writing has a depth issue

Demoralized by the advent of LLMs, I see tech writing communities break ranks and flee. In a world where coders who write seem to muster more respect than writers who code, the response from tech writers to the challenges posed by the intersection of automation, multichannel delivery, and docs-as-code is weak, if not absent. Conferences and blogs mostly focus on soothing anxiety and perfecting praxis. Nothing wrong with that, of course, except that it’s an intellectual dead end.

This lack of introspection is painful to watch

Recently, Scott Abel published The Great Documentation Brain Drain, where he was lamenting the retirement of great experts in information architecture. I’ve been mulling over this topic ever since I read Scott’s post. You don’t have to dig too deep to find out that the last book on technical writing to have had a semblance of resonance was Anne Gentle’s Docs like Code, published in 2017, perhaps one of the few that is not a self-promotional pamphlet. Scott writes:

Technical documentation […] is at a crossroads. If we don’t invest in the next generation of experts […] we’re looking at a future where companies try to automate away problems they don’t fully understand, and the only available documentation training is a two-hour webinar hosted by someone who just discovered Markdown last week.

You might argue that this is a big nothing burger. After all, technical writing raison d’être is to support engineering efforts from the side. Theirs is the powerful, creative mind; ours is but a tactical addendum, a set of pragmatic behaviors and tools suited to the task of conveying instructions. There’s no depth in this, you say after having saved a product from certain failure through words alone. I stare in disbelief when writers diminish their achievements like that.

While entire books and conferences are being dedicated to frameworks of a specific programming language, say Angular, writers still wonder if what they do is interesting enough to warrant a track at KubeCon. It might not help that most tech writers have come from a variety of disparate backgrounds, orphans of strong academic fields, but the same can be said of software engineering. And yet there they are, commanding higher recognition and not shying away from theorizing.

Sit down and start thinking out loud

If we attribute any value to what we do, any redeeming quality at all to the craft of technical communication, I think we should be thinking more and more deeply about our work, extracting principles and ideas, perhaps even creating what philosopher of science Imre Lakatos called research programs. Even before that, we should start thinking out loud, blogging more about our personal experiences and sharing thoughts candidly about what could be done better.

Writing about writing is hard. Writing about technical writing can be even harder, especially after long weeks of writing for a living. No wonder, then, that tech writers prefer to write about other stuff, or even jump to science fiction (like Kurt Vonnegut or Ted Chiang). That’s fine, though it contributes very little to shining light upon what we do at work.

Leaving these conversations to tech writing companies, CMS vendors, and tech comm marketers risks depleting the field of innovative ideas. Tech comms can be a business, but thinking is not selling: it requires intellectual freedom and courage. Leaving these conversations to engineers risks turning technical communication into a caricature of itself, a four-quadrant fantasy devised to lure developers into thinking that documentation is a simple pastime, yet another Jira task.

Only independent thought can help us progress and navigate uncertainty, including our future in a world where AI is injected into every domain that deals with words. Technical writers must own their problems and the conversations around them, or they will slowly fade into irrelevance, their problems absorbed by other disciplines that have more pressing problems to focus on. And if you’re reading that we should lobby more, you’re not wrong: defending knowledge requires power.

Where are we? What can we do about it?

I want to read more blog posts like Tom Johnson’s Do developers need code samples, because they dare question the status quo. I want to read more books like Docs as Ecosystem by Alejandra Quetzalli, because they offer novel ways of looking at problems. I want to see more sites like Manny Silva’s Docs as Tests, because they show that we can build bridges between disciplines. I want to see more theories like my Seven-Action Model, because settling for one is harmful.

It doesn’t have to be grandiose. If reading philosophy taught me something, it is that thought can be valuable in any form, provided it’s original. Do you want to compose aphorisms about tech comms? Go for it. Write a song, record a video, discuss other people’s ideas. You are important because your work is. Narrate your failures and your wins. Telling your day-to-day routine might reveal patterns or enlighten those who are new to the field. There’s nothing banal in existence.

The depth I’m advocating for isn’t some academic luxury – it’s essential for our survival as a profession. When we stop at the surface, we concede that our work is merely technical, not intellectual. We unwittingly make the case for our own replacement. But when we engage in the why behind our work, when we develop theories and challenge assumptions, we’re doing something machines cannot. This kind of thinking not only improves our practice: it defines why it matters.

So, paraphrasing Scott Abel: write it all down. Write it all down now.