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 is a post for beginners. Specifically, it’s a post for technical writers (regardless of specific job title) who want to learn more about API documentation, a realm traditionally separated from other forms of software documentation, and often made mysterious by folks who don’t use it or make it.

That I find this post necessary says quite a lot about the state of software documentation and the technical writers who produce much of it, but that’s a point I’ll explore in more detail another day. For the time being, I want to offer advice that’s meant to complement what other technical writers have said or written on the subject.

Here’s the why of my advice, which is bigger than just API documentation. In case you hadn’t noticed (and it seems that this particular rearguard action is still being fought), the new (or renewed) world of software documentation is moving rapidly toward a world that no longer isolates writers in their own little silos with their own proprietary tools and workflows to which no one else has access. This is particularly true for developer documentation, of which API docs are (partly) a subset. So if you haven’t done it already, you need to start thinking of yourself as part of a product development team, not (just) as part of a documentation team. You are writing with and for product teams, and especially for product managers and developers. Which means you need to turn yourself into as much of a PM/dev as you possible can.

So, try shifting focus. Stop reading about “API documentation.” At least for a while. And start reading about APIs. Specifically, read about REST, because that’s what almost everyone means by “API” these days.

(As I write, the one highly visible exception to the mainstream equation of “API” with “REST” is the Oracle v Google case. But the high level issues around what an API is are still the same — they are all interfaces, surfaces that other things can connect to without knowing what’s underneath the surface. And indeed, they should not know.)

Try some of these suggestions:

  • Read API and developer blogs, and read up on the major API management platforms. Yes, these are commercial ventures, but the folks who have built them have invested a lot in educating communities about APIs and in providing great information that any aspiring API documentarian should be familiar with. Here are just a few of my favorite resources. This list is not comprehensive — explore on your own and come up with your own set of tabs and bookmarks of similar material.
  • (shameless plug) I said not to read me, but I mention a few other good resources (tools, folks to follow on twitter) in this interview with Jennifer Riggins on APIEconomist.
  • Attend local API meetups.
  • Learn about OAuth 2.0 (and about the controversies surrounding it). I mean really learn — read the spec, and read a lot of different docs (about different implementations — everybody implements OAuth in their own way, because it’s not a tool, it’s a specification).
  • Learn about API security — properly speaking about web security more generally. Learn about certificate stores, and encryption. This, with OAuth, is an area that far too few folks pay sufficient attention to, and it badly needs the help of good documentarians who can help developers understand its importance and show them good security solutions.

Remember that the developers who are the audience for API documentation are users, too. Developer Experience (DX) is your new UX. As you learn more about APIs, you’ll learn about good API design, and this is tremendously important. As with any other interface, if you’re having a hard time documenting an API, and the docs are getting complex and convoluted as you chase down tangled details, chances are the API could use a good redesign. Catch these issues, as you would poorly worded GUI text or a badly laid out GUI, and you’ll make life easier for everyone. (You’ll also help evangelize the role of writer as a key member of the product dev team while you’re at it.)

I’ll post a separate list of my favorite discussions about API documentation.