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.

Regards,

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.

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.

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.

I didn’t mean to dive into this kind of topic so early in this blog’s history, but then it just sort of happened. This post is much later than I planned, some things happened at work, and I just talked about tools for REST API documentation at a recent WriteTheDocsPDX meetup. So related issues have been on my mind for a while.

APIs need writers. And not just for documentation. Let me explain.

Earlier this year, I came across a talk at GlueCon titled “Why Your Next API Should Be Designed By a Linguist,” by Rebecca Standig of keen.io. I still have not read or listened to the whole talk, but the title alone stuck with me, and keeps coming back to haunt me. There’s a lot more to Rebecca’s argument than the kind of thing that I talk about here, but it’s part of the inspiration for this post.

I’m talking about REST APIs here, but the same points apply to any sort of programming interface. Or any sort of interface, period: CLI, GUI — ultimately they all come up against the issue of usability, or user experience. The importance of usability and user experience varies, of course, from interface to interface — who are its consumers, how can it be explained, how can information be exchanged across it.

As it happens, my first experience with usability as it relates to programming interfaces wasn’t with regard to REST, and I didn’t really know much about programming at the time. I was a mere editor of programmer documentation for a well-known platform that I won’t name here. A new version was under development, and the writer handed off a draft of the docs to me for review.

I sent back a redesign of the APIs — although at the time I didn’t quite realize that was what I was doing. But I offered a reorganization — what writers call a developmental edit — and some renaming suggestions. As I recall, it was difficult to figure out just what was supposed to happen when, and I thought that changing about some of the words could help.

It did. I wound up in a room with the writer and one of the architects for the project, and the APIs were redesigned according to my suggestions. (I prefer to think that the fact that the project never saw the light of day was unrelated to my proffered redesign.)

Fast forward several years. I’m now responsible for documenting two sets of REST APIs, one of which is planned from the start for external consumption. The other has grown out of a larger project to rewrite an entire large enterprise server product with REST APIs to support the GUI. At least, supporting the GUI was the original intent — but as I’ve been able to piece together the story, somewhere along the way the product manager thought, hey, our external customers could use these APIs too, and we could provide a much-requested enhancement to enable customized scripting against the server. (This is an on-premise server, not a public one.)

The trouble is, as we all know by now, APIs that are designed and written for internal consumption do not always match the needs of external customers, and vice versa. The reasons for the mismatch are many, and vary from API to API. Here’s what I’ve seen, though, that a writer can help with:

  • Clear, consistent, sensible naming. Why inflict an endpoint called /foo_queue on any consumer of the endpoint, when /foos complies better with REST standards and doesn’t lead the customer to wonder “why a queue?”
  • The analysis that leads to clear naming can also contribute to API design. Naming is potentially complicated if the resource in question is a server object. Often the client is really most interested in the object behavior, which can make it tricky to name the resource in a way that indicates both what the client/customer can expect and at the same time comply with REST standards, wherein resources are always nouns. But if you look at the problem in this way, you can also turn it on its head. (And here I suspect I may be getting a little closer to what Rebecca is talking about with respect to the intersections between linguistics and software programming.) How you design the server object itself — how you create its grammar and syntax — is deeply affected by how you think about the words you use to describe and name its components. There’s a lot more to say about this issue, but I’ll save it for another post. The main point here is that people whose job it is to describe things in words can help understand how to make the things that the words describe.
  • Coherent organization. At a software design level, this is obviously related to the previous point, but I’m trying to stick to the writer part. We organize doc content around customer jobs — tasks, workflows, and supporting overview/conceptual and reference topics where applicable. This organization applies to any kind of doc, for a GUI-based product or for an API, with the caveat that the API docs are dominated by code examples, which show your developer customer what to do (instead of just telling them). But you also need reference docs, and they are harder to manage if you haven’t laid out your APIs in a thoughtful consumable order, especially if you’re generating docs from your code annotations/comments/docstrings.

Some product teams that develop APIs explicitly include writers as part of the core team. I worked this way briefly, and my co-presenter at WriteTheDocsPDX does now, at Salesforce.com. It’s good for the docs, obviously, but it’s also good for the product — the APIs themselves.

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