The Importance of Technical Writing

I started my career as a technical writer. I wrote manuals. I was fairly decent at it, though more than one of my editors would tell you that I was a bit too verbose (yes, I know, shocker).

I gave up on technical writing as a profession in 1999 after taking a course and realizing, that yes, it’s horrifically boring.

That’s not to say that it’s not valuable, however. While I might have been bored to tears personally, you had better believe that I retain every gram of the skills I learned and I apply that to (nearly) everything I write.

Good gods, why would I do that? For one simple reason: Technical writing provides structure and flow. If someone’s written a process well, there should be a clear understanding of how something is done, and if it’s a set of processes, it should be so well patterened that there’s zero question on terminology, formatting, readability, and references. It’s to the point of cookie cutter, where it should not just be obvious, but you should be able to infer from anything else you’ve read that you can literally expect what comes next.

That’s good technical writing.

And, holy shit, for someone like me – who’s spent far too many years of their career having to write out technical mumbo jumbo in a way that people whom I’ll never meet should inherently understand given a basic background – to be subjected to poorly structured and edited material is just so very, very frustrating.

Right now I’m embroiled in required training for a CRM platform that’s used extensively in the pharmaceutical industry, the section in particular is to – wait for it – send emails. Yep, that’s about it. There’s way more to it than that, but this is the only section that we need to pay close attention to.

Now, for the record, I’ve written so many HTML emails over the course of my career that they actually generate a tic if anyone asks me about them. Thankfully, in our day and age, it’s easier to deal with them than the past, when we had to deal with a dozen different patch versions (that’s when the version number looks like X.Y.ZZZZZ; the last bit is a patch number, which can get pretty complicated on its own) of Lotus Notes, where a few insignficant digits could lead to wild differences in the final render. Most email systems render emails pretty much the same way, with some minor (and ignorable) differences.

The platform I’m training on is more or less the same: templates that can include placeholder tokens that render out content in the email when it’s officially sent, similar to the merge sends of yore.

The key difference is the level of control imposed in the system, because the pharma industry has a number of (mostly self-imposed) rules to keep things sane. (This, incidentally, is why when you see an ad on TV for something vaguely medicinal that they don’t actually tell you what it does, just the condition, and “talk to your doctor”.) Let’s just say that lawyers continue to ruin all the fun.

The controls bleed into this CRM platform, too. I’m currently 45% of the way through a 10-part, hundred-page (or so it feels) training manifesto. And I cannot describe to you the sheer hell of having to keep track of all the notes and images to make sure that I’ve got the details.

Why, you ask? Because I’m being tested.

The test, for the record, is this: Perform an action based on the information you’ve just learned, on this set of imagemapped pictures with Javascript functions that judge your ability to understand. And, by the way, you have only one method for execution, which is deemed to be the “most efficient” (by … someone). Except that this is for a CRM, and I’ve yet to meet a single CRM that doesn’t allow you to solve a problem in any number of ways.

This means that if you click in the wrong place, even once, you FAIL. There’s no grace, there’s no “keep going, we think you know what you’re doing”, it’s just BZZZZZZZT.

Worse still, there’s been tests of material that are literally impossible without having to explore. Which means random clicks that I’m not allowed.

The language changes constantly. Proper nouns shift into regular nouns. Terminology is sometimes skipped. Step-by-step approach becomes a run-on sentence.

Look, I’m not a syntactical fascist, but if you’re expecting people to be certified on something, give them every damned tool possible to pick it up.

Gah. I had hoped that this little rant might blow off some steam. But it’s not. I feel a lengthy document sent to the vendor with notes with how to fix all this nonsense in my future.