Subtitle: What do technical writers do, anyway?

About two years ago, I had an at first dismaying but ultimately enlightening conversation with someone I met socially. She asked what I did, and when I told her that I was a technical writer, she said, O really, I used to do that too. What do you write about? I said that I wrote software documentation for programmers and system administrators, and she replied, O, and do you really understand what you write about?

At the time, her question simply made no sense to me — how can anyone possibly write about things they don’t understand? Two thousand years ago, the great Roman orator and great-grandfather of the study of style and persuasion, Marcus Tullius Cicero, wrote that we cannot speak well (and by extension, write well) well if we do not have something to say. In the language of the web, presentation depends on content. He would have been puzzled by the notion that one could write about something that one did not understand.

Yet in the world of software development, the assumption is endemic that writing is something distinct from the subject matter that it presents (or indeed more generally that presentation can be divorced from the content that it presents). Project managers, programmers, and writers alike tend to operate with a model that assumes that Subject Matter Experts (SMEs) provide information, and writers turn that information into useful, or at least somewhat more coherent, English instructions or information for the software customer.

When I wrote the first draft of this post, in frustrated response to the question about whether I understood what I wrote, I thought that this model was beginning to fade, or at least to be challenged. But it’s emerged again in one of the last places I expected to find it, the Write the Docs general Slack channel. The other day as I began to revise yet again, it appeared in a fairly extended Twitter conversation. So I decided it was time to get the post out and finally publish it. This is difficult stuff to write about, and I’ve been dissatisfied with every attempt I’ve made to get it down. But it’s clearly too important to leave in the Drafts folder any longer.

Writing as a mode and role distinct from subject matter expertise is not really about writing, it’s about editing. And generally, if you don’t understand what you’re writing about very well, you’re not doing the writing part very well. Writing and understanding are two halves of the same coin. (By extension, too, if you don’t understand the subject matter, you’ll almost undoubtedly do a terrible job of editing.)

And in the real world, the best technical writers understand very well what they’re writing about — usually better than the folks who built whatever’s being documented. Writers’ backgrounds are not all in software development. But good tech writers know both how to construct good English sentences and paragraphs and how to research product functionality, how to identify missing information, how to test the product — they are far more than expert editors of language. Their skills lie equally in their command of language and in their ability to research and understand both the processes required for software development and the domain-specific knowledge that an application helps manage. They are good at understanding the customers of the products they document, too — they often possess formidable user experience expertise.

How and why have these skills and contributions come to be so little recognized or under-utilized? I think the answer is two-fold.

First, the persistent arrogance of the world(s) of software programming generally. Programmers aren’t trained as steel fabricators or security analysts or project managers (to take a few examples from the kinds of software that I’ve helped document over the years). They’re trained to write code. They learn as much as they need to learn about the subject matter that an application helps manage, when they need to learn it — and therefore also about the customers for the software that their code contributes to. But their basic skills lie in breaking down any task into sufficiently small components that each component can be translated into a set of binary instructions. We’ve all seen too many times, however, the tendency of “the truly technical” to assume that their fundamentally limited skillset can be applied to All The World’s Problems: the Greek economy, the sad state of education in the United States, and even urban planning and infrastructure.

Of course, to do a decent job of breaking down any individual domain’s tasks into code-able bits, programmers do need to learn the domain, or at least enough of it to work on their assigned bits. Technical writers, on the other hand, inevitably must help to explain all those bits, and to put them into the larger context of managing the domain, which the entire software package presumably will help the customer with.

No domain-specific knowledge is necessarily assumed up front for either coders or writers, and expectations and skills around customer knowledge and understanding vary wildly between individuals and across projects and companies. Somehow over the years, though, coding has come to be seen as an arcane art, related to Math And Other Scary Things That Most People Cannot Understand. (And the notion that we just need to do a better job of instructing in the Dark Arts of STEM only reinforces the notion that coding is More Special Than Everything Else, no matter how many conference panels are organized around the theme of “non-technical contributions are just as important …”)

But here we come to the second thing.

Technical writers themselves have contributed significantly to the perception of their work as separate from both software development and domain knowledge. Documentation, technical writing, and the currently fashionable jobs of user experience designer, information experience manager, information architect, or content manager, with which software documentation is or ought to be closely associated, have become highly professionalized to a remarkably content-free degree. Conferences for people who call themselves technical writers, with the notable exception of Write the Docs, tend to focus on specialized documentation tools or on “content marketing” (a term whose ambiguity suggests that perhaps the real word people aren’t participating much in its discussions any more either). The ambiguous if not entirely meaningless term “technical communicator” has come to be associated with this empty professionalization that seems to know only how to speak to itself. Software development generally suffers from a tendency to create and reinforce silos around product development roles, no matter how much “agile” discussions may challenge some limited aspected of this tendency. Writers are almost invariably excluded from any efforts to collaborate across roles, but far too many of us seems to prefer it that way. Instead of true collaboration, we rely on specialized documentation tools and workflows to which we allow no one else access, we assume that Other People Know More Than We Do, and we turn ourselves into marginalized tools monkeys, scrabbling for the leftover scraps occasionally tossed to us by The Really Important People.

How can we expect other members of the product development team to take our skills and contributions seriously if we don’t do so ourselves? Let’s start by eliminating the term and the notion of “Subject-Matter Experts” from our own vocabularies, and working to educate the rest of our teams about what we really have to offer.