So clear, you can see the Dr Pepper

Well, today I’d hoped to tell you all about the blog setup process, but we still haven’t installed Docker/Jekyll for Windows on my desktop, so I’m not ready yet. I can see some of you stifling yawns. Look, it is my job to make this kind of thing sound interesting, so I’m going to write about it anyway, and hopefully everyone reading will kind of understand.

My favorite kind of writing is to take something technical and explain it so a lot of people are engaged and understand, but no one feels like I’m treating them like a kindergartner. That’s the part of technical writing that makes it fun and interesting, instead of dry and boring like some of you might imagine. It’s also difficult as hell. Writers block is common and I have a dozen nutty little rituals to kick-start myself including but not limited to walks and music and snacks. People who have worked with me awhile know that if they see Cheetos and Dr Pepper on my desk instead of the usual slowly disappearing cold brew, they should tiptoe away.

(Actually my favorite kind of writing is to rant here and there about 30 different crazy things, with footnotes, but it doesn’t pay quite so well as the technical documentation.)

For example, a few years ago, I had a meeting at work (different work than now) with some API writer/developers. We wanted to overhaul our company’s API documentation website, which at the time was bare-bones and didn’t promote the wonderfulness of the APIs as well as we thought it should. I was half-interested because API documentation sounded like the most boring thing in the world. I hadn’t done a lot of it, but the idea of writing dry reference stuff for developers made my whole face yawn.

One of the API writers decided we might be inspired by looking at some other websites’ developer-facing documentation – an obvious place to start would be Google. I don’t remember the other sites on his list, he was right – we were inspired. I understood, not for the first time, that writing you think will be boring doesn’t have to be boring. I thought API docs were, frankly, engagement-proof. And yet here I was, actually reading and understanding material on the Google Developer site, which at the time (and possibly now, I haven’t looked lately) was written in a simple and engaging manner.

Of course, Google has oodles of writing, design and developer resources so they can produce a beautiful site like that, where we weren’t able to do much more than some judicious editing here and there, maybe a few layout changes, before we were all pulled onto higher-priority projects. I seriously considered moving into API doc work, and I still might, for the challenge of it.

With all the love to our developer friends, they often tend to favor passive voice, annoying verbs like “pass” and “call” that can be vague, lowercase letters for everything ever, and a lot of jargon and abbreviations. In fairness, a) I’m stereotyping and b) they’re doing this because of speed. They’re writing in a hurry – they’re devs, not writers – and they want to read their docs in a hurry and not have to stop to deal with extra words. The idea that extra words might help them read and comprehend more quickly is one that a good writer needs to sell carefully.

A good, smart technical writer should be able to take a developer’s shorthand-y, almost cabalistic writing and craft it into something that larger audience can read, not just the dev team involved. A product manager trying to estimate resources. A writer who has to install this stupid Ruby gem on her Windows desktop. A support person trying to help a freaked-out client over the phone. You get the idea. It can be clear and short and yet elegant and engaging.

It’s a pain in the ass to write this way, especially with developer input and approval. You end up going back and forth with the developer about What Is The Actor In This Sentence and Capitalize “bash” Or Don’t, But Pick One and Be Consistent. For procedures, you do them yourself and then you go find another writer or non-technical person and try to get them to use your instructions to see if they work. If you’re me, you end up having a discussion with yourself about putting down the Dr Pepper.

I thought about changing my LinkedIn tagline to “Content So Clear, Your Mom Can Understand,” which I thought was catchy in a Calgon sort of way, but decided it was too offensive from an ageism and sexism point of view (although I may be the same age as some of these developers’ moms). But this is why I like technical writing. When you get it right, you end up with something that is useful to more people than just a group like the developer who put it together. You get something someone will actually read and understand. From a business point of view, this saves money in all kinds of ways. And from a writer point of view, it is infinitely gratifying.