Writer
Image courtesy of Neil Newton

I’ve mentioned before that I am one of those lucky few that (in general) actually enjoys his job.  I like working in high tech, being around smart people, playing with cutting-edge (“bleeding-edge”, we like to joke) tech, while at the same time not writing code or designing hardware, two areas in which I studied and got a degree but for which I am depressingly untalented.  Writing about tech stuff, though; there, I seem to have a degree of ability, thank goodness.

That doesn’t mean, though, that the job doesn’t have frustrations.  Now yes, “Check your privilege”; these are first world problems, and for a cis-gendered, straight, white male.  I don’t have to deal with the rampant sexism in my chosen field (though I try to mitigate it where I can).  I don’t have to deal with racism, except in those rare cases where I have worked in a majority non-American environment (it happened a couple of times).  I don’t have to deal with homophobia or transphobia, and as I don’t go around wearing a yellow Magen David and don’t particularly “look Jewish”, the minor amounts of anti-Semitism I’ve encountered haven’t been a big deal.  Duly noted.

But in nearly three decades of professional tech writing, I have to admit that I’ve gotten pretty tired of some things that happen consistently, again and again and again, no matter how much I try to fix them.

In the high tech world, I should tell you that tech writers are pretty low on the totem pole.  Engineering believes that Marketing, Support, and QA are in the same region, but as Marketing knows they’re not, it never hurts their feelings.  I have on the other hand commiserated plenty with Support and QA folks, who are treated as (at best) necessary evils.

You see, the engineering attitude is, if they write awesome code, there’s no need for Support or QA; why test and provide support for something that’s awesome?  And Marketing?  Ha!  My code is so awesome that it will sell itself; what do I need those suit-wearing, MBA jargon-spouting fools for? (Of course, since Marketing feels similarly about Engineering—”Don’t those idiots know that if we don’t sell their product they wouldn’t even have jobs?”—that part kind of evens out in the end.  And besides, it’s the Marketing folks who tend to move up the ladder and become CEOs.)

Technical content?  Despite the fact that we supposedly live in an era where “content is King”, most people believe that it’s easy, that it’s just “cut and past from the specification”, that it’s just “ink on the page”, that “one of my engineers can do it”, that everyone can write the content if they didn’t have to spend their extremely valuable time writing code/being a manager/doing important Marketing work/whatever.  It’s like breathing; everyone knows how to talk, so everyone knows how to write technical content, right?

Well, um, no.

Like everyone else in high tech, technical writers have spent years (or even decades) honing their skills.  While everyone theoretically can write, the number of people who can write clear, concise, correct colloquial American English is pretty small.  People assume that that because they can speak, they can write. It’s simply not true.  The number of people who can do that and comprehend high tech concepts, software, and hardware is even smaller.

Now then, let’s look at me.  I spent 4 years in college—and plenty of time in high school too—learning computer technology.  I started when I was 15, and got a degree in computer science.  I did the work of going into a job as an engineer.  There’s not too many people who do that and then don’t become engineers.  I also had some inherent skill at writing, and since entering the field, I have spent more than 20 years working on my tech writing skillset–not just my writing, but theories of organization, information architecture, web page design and layout, editing tools, publishing tools, source control tools.  And I’m hardly atypical.

Despite this, tech writers constantly have to remind people of their ability.  I’m often tempted to say, “Hey, I don’t lean over your shoulder and tell you where to put curly brackets and semi-colons in your code, do I?”.

Tech writers also have to teach every new product team that, yes, we do understand technical issues and yes, we are professionals on par with them in our own branch of the high tech industry and, finally, yes, they have to take us and (more importantly) what we do seriously if we want to get the durn product out the door.

And finally, it becomes very tiresome to have to behave like some kind of fascistic, yard-stick weilding equivalent of a Catholic school knuckle-smacking nun in order to get you to do that part of your job that intersects with mine.  Yes, I read the specs; yes, I try to use the product myself; yes, I attend the appropriate training classes (when they exist; for new products, they don’t).  Yes, I do all that.  But I also need a couple of things from you: When we ask for some of your time, rather than being grumpy, snarky, suggesting (either implicitly or explicitly) that we haven’t done my homework, do us the courtesy of providing that time.

Because see, if you give us just a little bit of time, not only will we document everything you tell us about, we’ll probably find other stuff that you and QA missed but that the customers won’t–I have an amazing gift for breaking software and finding odd corner cases–and we’ll document that, too.

Truly:  30 minutes of your time now will save you hours of hassle later.  I’ve been doing this a long time; I know. (Also, it provides you with some good CYA.  “I met with Doug on this; isn’t it in the product documentation?”  See?  Off the hook!)  Wouldn’t you rather spend that time chatting with me instead of arguing with trolls on the forums, dealing with irate customers via phone, or having an exec email you demanding you fix some problem?  It’s a good investment!

The other thing we ask is that, when we send you something to review, review it.  Look, I know reading technical content is the last thing you want to do.  I know it’s dull.  I know you think your time is too valuable for it, that someone else should be doing it, that I should have gotten it right the first time, that there’s no time in the schedule for you to review content.  I’ve heard it all, believe me.  (And if there’s no time, please tell me; I will go all the way up to executive VPs to get time built into your schedule for it.  Trust me; I’ve done it.  Ask my friend Margaret.)

But unless the experts—”subject matter experts” we call ’em, or SMEs (because in high tech it’s not important until it’s been assigned an acronym, even when that acronym is made up of other acronyms)—go over my content, it’s going to be wrong.  I’ll catch most stuff; hell, I’ll think up plenty of stuff you folks never would (remember my lecture on how much experience I have earlier on?).  But there are technical minutae that I will miss.  I can’t help it; you’ve been coding that project for six months and I’ve only been playing with it for a few weeks; how could it be otherwise?  If you didn’t know more about it than me, we would be switching jobs no matter how lame my coding skills are.  That’s what review teams are for: To catch the stuff I miss.

(And by the way, don’t worry about my grammar, punctuation, and other writing-specific things.  I know there’s a terrible temptation to mark those things up; it’s easy, it’s obvious, and it gives you a way to get back at the person who’s “wasting your time”.  Resist.  I know you can do it.)

So there you have it.  As writers, we don’t ask much.  Just

  • Treat your content people as fellow professionals whose time is also valuable even though they don’t code or design hardware
  • Give them the time they ask for (and if they’re asking for too much, go to their managers)
  • Give them the feedback they request

Do that and not only will your content person be really happy with you, they’ll do you favors.  They’ll post bugs that they found in the product that everyone else missed; they’ll help you re-word that email to the exec to help you get off the hoook for that major screw-up; they’ll advise you on your resume when you’re ready to head on to new challenges; they’ll give you solid advice on your web site that you never would have thought of.  This is the kind of stuff we do.  Leverage it.

The few; the proud; the technical content creators.  It’s not just a job, it’s an adventure.  No, seriously.

Advertisements