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.

Not part of my (ir-)regularly scheduled programming, but too important not to put here.

I live in Washington, DC, where we have no elected representatives. Which means that if you are outraged by current events, it’s a little hard to do the Standard Thing and write to your congresscritter or Senator.

So I’m writing (and calling, and delivering paper in person) to the Senate Majority Leader (Mitch McConnell) and the Speaker of the House (Paul Ryan) (yes, the bitterest of ironies …). I’m calling on them as congressional leaders, who ought therefore to take special interest in the concerns of DC residents since we are supposed to be represented by All of Congress.

If this idea appeals to you, but if you want some help getting started, here’s what I’m saying (please feel free to adapt — in fact, I encourage you to do so! But do copy if that’s the only way you’ll get it done.):

Dear Senator McConnell | Congressman Ryan,

As Senate Majority Leader | Speaker of the House of Representatives, you have an extra obligation to me and to other citizens of Washington, DC, because we lack territorially based representation and must therefore depend upon Congress as a whole to respond to our needs and concerns.

I write to urge you to abandon your enslavement to the gun lobby and to act as a true leader in helping to enact the right gun control legislation. We desperately need laws that require background checks on anyone who tries to buy a gun in this country, and that ban sales to dangerous people. Danger comes from many places: from mental illness, from known histories of violence, from terrorist watch lists.

Gun violence in our country has reached epidemic proportions. We should have worked harder to stop it after Sandy Hook. But now, in the wake of the Orlando shooting which represents the second largest terrorist tack ever on American soil, it is beyond time to take action.

I urge you strongly to lead the Senate | House of Representatives in putting strong background checks on gun sales in place across our great nation. These background checks need not impinge on the Second Amendment; instead, they can only help to ensure its appropriate enforcement.

Thank you for your attention.


Jennifer Rondeau
Washington, DC

This weekend I’m (finally!) at IndieWebCamp, where I’m doing some new things to my site and not incidentally putting the site out more publicly. It’s exciting, because before I started the site, as I’ve mentioned before, I had loftier ambitions for what I wanted to build and how I wanted to manage things. IndieWeb was part of those ambitions, so the weekend feels like a return of sorts to a bigger vision of what I might eventually do on the web.

If you’re not familiar with IndieWeb and microformats, check them out!

And instead of liveblogging my efforts to continue the IndieWebification, I’ll just keep adding to this post.

I’ve now changed my theme, because the new one fully supports microformats2, but also because it is more fully semantic, which pleases me even if I’m not working directly in the HTML myself. It’s also reasonably in keeping with my previous theme, although I do want to tweak the CSS a bit. In all that free time I have to work on this site, y’know. …

I’ve been trying to understand my own uncomfortable reaction to a lot of discussions about software documentation. To most of them, in fact.

I write documentation for a living, and I find the challenge of writing good docs pretty compelling. So why do I squirm and feel like running away every time someone I follow on Twitter posts a link to another resource about documentation? Why do I try to avoid most of the standard resources in my chosen field of endeavor? I don’t mind telling people what I do, and like many folks who care about good docs, I am in love with the Write The Docs conferences. So what gives?

Part of the answer lies, I think, in the title of this post. It’s also part of the answer to why I was uncomfortable for so long with the idea of even starting a blog (and why I’ve malingered over really getting it going).

As I see it, writing documentation is a thing you do, not a thing you discuss in the abstract. Or if you discuss it outside the context of a particular deliverable, you do so in immediately practical ways: what’s the most appropriate way to call out a particular kind of UI element (or should you even call it out)? How should programmers and writers jointly contribute to Javadoc comments? What are some good ways to organize a programming guide/a user manual/a knowledge base? What does this error in my doc build mean and how can I fix it? What’s the best way to support localization?

These aren’t, obviously, the only sorts of documentation questions people are interested in, or even the only sorts of doc question I care about. But more abstract discussions often very quickly move into generalizations about Documentation As A Self-Evident Truth, and that’s where I think my discomfort starts. This is what I’m calling “fetishizing.” Documentation Matters, doncha know. Good Documentation Can Save The World.

And There Is One Right Way. Thou shalt write according to the dictates of “structured authoring” — a term that continues to bewilder me, even though I work within the constraints of some of its dictates. What does “unstructured” authoring look like? And does anybody really “author” software documentation? (I sure hope not …) Or thou shalt “single-source” — a term whose practical meaning has looked pretty slippery to me over the years. Or use a particular toolset/platform/workflow. Or not. (Just ask a group of folks who write about “agile” …)

Context. Context is what fetishized documentation discussions lack. If your doc content, however it’s organized, however it’s presented, gets the job of helping your users get their jobs done, that’s what matters. Sure, there are ways of thinking about and organizing docs that can help you achieve this goal. But ultimately it’s your product and your users who matter, not the theorizing of folks who are overly invested in whatever the latest doc trend might be. And maybe it’s ultimately that lack of context that makes me uneasy when doc discussions go all abstract. All the carefully chosen stories or examples that prove the abstract point can’t make up for the fact that somebody else’s abstraction does not take your context into account.

Maybe inspiration will stick this time. I hope. I will also never put the word “procrastination” in a title again. Proleptic, much?

More than a year ago I was inspired to start what became this blog. It took me half a year to get the thing up and running, and more than six months since my last published post, I’m only now getting around to blog post #3 (although in my defense I would like to state that half a dozen or so posts languish in draft state).

I have Real Things I want to write about, but I also feel the need to provide some kind of interim narrative. I’m not sure who I’m writing for — myself, as I think is obvious, but the existence of this blog means that I’m also writing for other people. I suspect that I need to stop worrying about this question of audience, though, because it’s one reason why it’s so hard for me to actually click that not-too-big blue Publish button.

The other reasons have to do with my background. First of all, I write for a living. I do not call myself a writer, however, because I do not have a passion for the activity we call writing. I like to explain things that I’m interested in, which is why I’m willing to call myself a technical writer (or “documentarian” — but more on that term in a later post). And one big set of things that I’m interested in have to do with what I’m paid to write about, namely a lot of stuff that’s related to software development.

So as someone who produces text professionally, I fuss about words. I’m paid to fuss about words. I choose to be thus paid because it appears that I fuss about words compulsively, and with a reasonable degree of what passes for competence in the current state of the English language.

I’m also an academic refugee, who spent decades of her life writing things that required her to produce data from which she derived her conclusions — or at the very least, References that could provide the Authority from which Conclusions Could Be Derived. In other words, I always had to prove my point. Show AND tell. Always be prepared to back up your assertions.

This background contributes to my apparent success as a producer of software documentation — TL;DR version: I’m a highly trained researcher. Ask me to write about something, and I will go find out about it. My work-related reading list is, shall we say, eclectic. (Currently open tabs are related to OAuth, OpenStack, content reuse, lots about API design, Python, Javascript frameworks, asciidoctor, systems analysis, the history of technical writing — and cocktails. Maybe that last one is only indirectly related to work.)

But ask me to write about stuff “just because” I’m interested in it, or care about it? Yes, I set myself up for it, but it’s proving far more daunting than I expected. I have to stop the compulsion to prove every point I want to make, to try to tell The Authoritative Story, to be The Expert.

When I put it like that, I think “ick,” in fact. That’s the antithesis of what I want to do here. I want to tell my stories, give my perspective, honor those who have inspired me but not lay upon them the heavy mantle of Authority. If I’m lucky, I’ll get to have conversations with the folks who eventually find their way here. And even if I’m not lucky in quite that way, I’ll have committed some of my ideas to a more permanent medium than the fitfully firing synapses in my own brain.

This blog, and the bigger website it wants to grow into, is a long time coming. For years I actively avoided the idea of a blog, lacking any sense of a clear purpose for such a project, and not caring to add to the general noise of the interwebs. Almost a year ago, that attitude started to change. I didn’t do anything else differently, I just started to realize that I did have something of my own to contribute to the professional discussions I’d been following fitfully for years. I also started to dream bigger about my professional goals.

I had grandiose notions of creating a built-entirely-by-my-very-own-self website using cool cutting edge (or at least fashionable) tools, showing off what I could do behind the scenes as well as with the words on the page.

Yeah, right. I still have those notions, but I’m also still working on turning them into realistic plans — quite a different proposition.

Then I attended a conference, my first professional conference ever in my second career (or third, or fourth, depending on how you count) — mildly ironic, since my first professional career involved a very large amount of conference-hopping. And … it was GREAT. Inspiring. I had even more to say, and groups of people I hoped to be able to discuss my thoughts with.

That conference was writethedocs PDX, back in early May. It’s now mid-September. And … yeah, it’s just a blog. On WordPress. No exploring new tech yet (new to me, that is). But maybe someday it will grow into some semblance of the site I originally envisioned. Or maybe it will morph into something altogether else along the way.

In case you find this page early on in the bloglife, and also to try to keep myself honest, here are some current potential topics, in no particular order:

  • Doc quality — how to test, assess, measure ROI
  • (Closely related) How do we define good software doc writing?
  • User research — how can we know which docs really matter? What customers really need?
  • OAuth and me
  • Swagger and me
  • APIs and me (mostly docs)
  • Learning to code on my own