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.


This post was conceived at OSBridge in Portland this past June, but its birth has taken a while. And in the meantime, this brilliant talk by Leslie Hawthorn, given at eurucamp 2015, appeared:

Leslie says everything that I say here, only better and more succinctly. If you want the TL;DR version, just go watch her. I had already written these words, though, and I want to tell my story as it relates states of being “technical.” Or not.

When it comes right down to it, we are all “technical.” And technology is everywhere in our lives, not because software is eating the world, but because human beings make all sorts of tools, and every single one of those tools is a technology.

“Techne” = “art, craft, skill”

“Technical” and its close cognate, “technology,” have come to be defined more narrowly over the past 50+ years, to refer almost exclusively to industrial and scientific applications (and those terms have in their turn been defined more narrowly over the centuries). But what’s happened to the word “technical” goes beyond simple shifts in usage over time. This word has become a key way to identify people — not things made by people — as belonging to a certain privileged elite. Or, in the case of “non-technical” — being ruthlessly excluded from that same elite. (Because then we can wring our hands over the “problem” of “bringing non-technical people into tech.” Whatever that’s supposed to mean.)

This matters not just because “technical” is a useful word in many contexts other than software programming. It’s important because this particular word has come to distinguish the coders — who are also The Most Important People — from everybody else. There are “technical” contributors to software projects, and there are “non-technical” contributors. And the technical guys (noun choice deliberate) stand tall over all the rest of us.

A few years ago, “technical” had already come to refer mostly if not entirely to software development, but its appropriation was a bit more general. When I started working at my present company, nearly eight years ago now, my manager told me that she had hired me in spite of the reservations of one of my interviewers, who had expressed concern about my apparent lack of “technical” knowledge or skills. What exactly that meant, nobody seemed to know. I certainly wasn’t expected to code. But being insufficiently technical was a thing, and was considered a cause for concern.

Fast forward five years. I’m compulsively curious, I like to learn new things, and I work with programmers. I’d been reading code for years (before my assessment as “not technical enough”), but now I learned to code, at least enough to write sample code for an SDK, and to work with the programmers on code comments to produce reference documentation. It was a proud moment when the SDK was presented to the company, the architect acknowledged my contributions, and he described my work explicitly as “very technical.” I’m sad to say, in hindsight, that I was proud at that moment. A Real Programmer had pronounced me Technical. I had Arrived. I was part of the in-crowd.

Because that’s the point behind current uses of the word “technical.” It separates the sheep from the goats. The folks with the real cred from everyone else.

And in the years since I was welcomed into the ranks of the “very technical,” the word’s definition has gotten more and more narrow. At two major recent conferences I attended, I encountered it extensively and pervasively, to describe only the act of writing software code. All the time. Testers not allowed. Only Real Full-time Programmers can be technical, in this view of the world. According to this world view, I no longer have “technical” status — but then, I no longer want or seek it.

Yes, I want to develop my coding skills, and to apply them more in my daily work. But I want no part of a taxonomy designed to mark an exclusive and narrow geek elite as fundamentally More Important Than All The Rest of Us. I want to challenge all such taxonomies, and the taxonomy of the technical and technology in particular.

When I started teaching with the web — which amounted to no more than putting my course syllabuses online, and updating them with links to external resources — I was in the vanguard of classroom technology. Most of my students had computers, but they didn’t all have Internet access. Those who did, had dial-up. Most of them accessed the web from library workstations. I still printed out paper syllabuses, and wrote the updates on the chalkboard. I wrote out my lecture outlines on the that same chalkboard, or took notes on the board if class discussion was the order of the day. Yes, PowerPoint was available, but I never went that route. (You really shouldn’t have to ask …)

I started every term with a pencil and a pen in my hand, together with the syllabus projected on a screen. And I took the time to explain that the laptop on my lectern and the pen and pencil in my hand were all technologies — tools made to help humans make other things. I’d mention the printing press — a taste of things to come in the Renaissance history courses I often taught. The astrolabe, the compass, the jacquard loom (an important progenitor of programming technologies), the automobile — these are all technologies. And I’d mention them. But I’d start with the simple pencil and pen because they were so accessible, and because they and the laptop computer — or more precisely, the web page that I was displaying in its browser — were equivalent technologies for the purposes of the classroom. It was absolutely vital that in bringing a new technology into the classroom I do everything I could to keep the classroom experience familiar, and accessible, and unthreatening. Like the world my students knew, not different from it. Representing continuity with the past, not break from it.

Sure, the context of those not-really-so-very-long-ago classrooms was different. But software development these days, and the rest of the world too, could use a more generous understanding of what technology means, what it means to “be technical” — a clearer-eyed and all-encompassing view of the many different techniques required to produce a piece of software, or any other human endeavor.

Software is eating the world, and its creators and masters are all too eager to stake their exclusive claims to the privilege that their work confers. Let’s take back one not-so-little word, and celebrate the whole of human technical endeavor.

The interwebs are saying the things that I’ve been thinking, here and elsewhere. My experience suggests, sadly, an interpretation more akin to Larry’s than to Mark’s. When a doc conference includes a talk about how “engineering” (don’t get me started on the the software appropriation of vocabulary that has more general meaning) processes should inform doc processes, and suggests that a conversation between “engineers” and “writers” should in effect be defined by the former — or when a recent entry into the doc publishing platform market says, all you need is a platform that makes it as easy to write docs as to write email, because we all write email (and yeah, we all know what effective communication email provides ;P) — well, the bar is being set (far too) low.

Apologies for the run-on sentence and the parenthetical asides. (At least I know ’em when I see ’em, *and* when I perpetuate ’em.)

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.

I keep writing and publishing posts about (REST) API related matters, when I keep thinking that I have more to say about The Whole World of Software Documentation. Some day I’ll figure out why. In the meantime:

I’ll start with a word-related peeve. Or, more precisely, a definition-related peeve. It also happens to be documentation-related.

Swagger is not a documentation tool.

Got that, writers who are presumably the guardians of vocabulary and meaning and precision and usefulness?

I’ve lost track of how many times I’ve seen this error repeated. I am not the only one to call it out — see, notably and more authoritatively, Kin Lane’s related post — but I am the only writer I know to do so.

Why does it matter? After all, you can do some things with Swagger to produce documentation, so why not call it a tool?

Because in fact it is something else. It’s a specification. And the difference matters a lot when it comes to producing either (a) documentation or (b) the multitude of other useful tools that Swagger is inspiring these days.

In fact, as I write, I realize more clearly than I have before just how much reducing the definition of Swagger (not to be confused with a “Swagger definition”) to a mere documentation tool does a great disservice to everyone who’s not already involved in the nascent space of API development. And even to some of those who are already so involved. It also does a disservice to those writers who don’t know any better, but who are approaching the world of API documentation for the first time and who might understandably be confused when they discover that no, Swagger doesn’t work like doxygen. Not even close. Swagger-UI doesn’t even work like doxygen. And again, not even close. Depending on your development environment, you may be in for a very rude shock if you start from this assumption (whether you’re a developer or a writer).

Naming things is notoriously difficult in software development. Mis-using or redefining words already in common and valid use *in the world of software development* only makes things more difficult. (Appropriating perfectly good words already in general use for very specific and unintuitive meanings in software contexts is a peeve I’ll save for another day.) This word person at least is trying to do her part to set the record straight for at least one term and its (software-related) meaning.

p.s. After I wrote the preceding, but before I published it, I learned that the Silicon Valley chapter of the STC has scheduled this meeting, which represents a move in the right direction. It focuses on RAML, not on Swagger, but in the context of my screed here that’s a minor detail.