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.

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.