The Death of Technical Writing

I’ll be blogging off and on about The Death of Technical Writing, so let me start by explaining the scope I’ll be talking about. I’m mostly talking about traditonal user documentation (publications and online help) for software. This includes enterprise applications, consumer “in the box” applications, web applications, etc.

This doesn’t include writing about how to use physical things, like HVAC systems, toys, etc., although writers for such products had better beware what I’ve always called “The Lego Effect”. Holly Harkness blogged about The Lego Effect using a different example: Ikea instructions. The Lego Effect is the use of pictures for 100% of the documentation. Unless your product can be documented with 100% pictures, writers with physical products should be OK when all the rest of us lose our jobs.

I once had a job documenting a physical product, and here’s why I think such writers are safe: you can physically hurt yourself with a physical product. And I think there may be a relationship between the degree to which you can hurt yourself and the prevalence of The Lego Effect. You can’t hurt yourself too badly with a Lego, but you can blow up a building with a Chemisorption Analyzer, one of the physical products I documented for the high-tech-rednecks* at Micromeritics. Put the wrong combination of chemicals in the analyzer, crank up the heat and pressure, and you’ve constructed a bomb, literally. So I think there’s some decent job security for whoever’s documenting that now. It would be fun to try to do a 100% pictures version of the Micromeritics doc, but I don’t think the lawyers would get behind it.

 So, summing up this introductory post, your job is safe if you write about a physical product that is potentially dangerous. You need to find a new career if you write books or help about a software application. And don’t think you’re going to segue into usability without another degree or certification, either.

 *Interestingly, the wikipedia does not define high-tech redneck in its article by that name. The HTRs at Micromeritics were physics-lovin’, chemisorption-peddlin’, deer/elk/boar shootin’, bow huntin’, grammar debatin’, homemade elk jerky eatin’ GA Tech graduates. Yippee, another chance to edit the wikipedia!

Don’t use “once” if you mean “after” (a Martha-peeve TM)

I think my former employees used to get really pissed off at me when I would remind them of the Martha-peeves ^TM. Maybe they were sick of hearing it, but then again, I continued to see the Martha-peeves in their writing, so I guess they waaannnted me to repeat myself. One that seemed particuarly annoying to them was my insistence that they not use “once” if they meant “after”.

Example:

Once you have copied the license text into the form, click OK. [wrong]

After you copy the license text into the form, click OK. [right]

Scott Abel, The Content Wrangler,already in my favorites list, is speaking tonight at the Atlanta STC Chapter Meeting on “the adoption of controlled vocabularies to help make content less ambiguous and to improve translation accuracy (and make translation less expensive)*” among other things. I’m looking forward to some vindication on the “once” issue, and I hope all my former employees attend. (OTOH, I may find out what crow tastes like )

All in all, for clarity, for controlled vocabulary’s sake, and for the translation advantages noted above, you should always choose the word with the fewest meanings, in cases where synonyms have multiple meanings.

I am again compelled to note that this post doesn’t apply to creative writers, copywriters, etc.

*quote from the Atlanta STC website

UPDATE: Scott gave a wonderful, humorous talk. It was a little more macro-view than I expected, but then again he only had an hour. Overall, I don’t think I’ll be eating crow any time soon I know I have way more readers on my blog than Scott does on his so I’ll mention that he has a really cool sounding social networking thing on his website (see above) for technical communicators to conglomerate and chat. I haven’t seen it yet, but it sounds wonderful and I encourage you to check it out!

NOT!

Remember the scene in Borat where the comedy coach (who knew?) tried to teach Borat about “Not” jokes? I’m getting ready to work with my dev team on “Not” rules. We let users create rules about who should be able to access network assets under various circumstances. In this version, we’ve added the ability to exclude specific users, groups, machines, etc., by checking the “Not” checkbox.

I don’t like it.

For this release, there’s just no time to rethink this feature. It’s a great feature, and one our customers have specifically asked for. I just think the implementation needs to change in the next release.

So I’m brainstorming…how can we do better? My friend (a user experience professional at a former employer of mine) has suggested working the feature around the word “except” instead of “not”.  It’s a good option; I’m just wondering what other approaches might make sense too.

More info: the dev guys seem to think that people who are used to working with firewall rules are down with “Not”. I’m just not entirely sure that’s our target user. What would a VMware power user call it?

Still more info: in our application, you can use the “Not” checkbox to exclude specific users, computers, applications, etc. from policies, thus indicating to the system that attempts by such users, computers, applications, etc. to communicate on the virtual network are not OK.  Note: in the screenshot above, the “Any” option goes away when you choose “Not”. We wouldn’t want to “Not” allow “Any” user to communicate, now would we?

Ideas?

Error: Configuration error device 0

Our company is working very hard to get a feature-complete build done, as we rush along toward our upcoming deadline. I myself need to get a bunch of screenshots into the help, then get the help into the build.

But <name of your preferred higher power, if any> always seems to have a little fun at our expense, doesn’t <he/she/it>? Our virtual infrastructure client (that which controls all the virtual machines on which we access our UI instances) doesn’t like me today. Well, I thought it was just me, but it turns out that everybody in development is getting an error message: Error: Configuration error device 0. And we are unable to access our vms, and therefore, the latest builds.

Nobody knows what device 0 is. Perhaps more information about exactly what the config error is would shed some light, but alas, there’s naught to be found. I’d like either a little more talk, or a little less talk and a lot more action (to paraphrase one of my favorite Elvis songs).

For <higher power>’s sake, people, figure out how to make your product’s error messages helpful! I guess I’ll go clean out my car now…and work on the help file at midnight.

Procedurelessness

I’m I’m lucky to work for a company whose developers really get it. They try very hard to make the interface self-explanatory. I’ll blog later on why this makes me believe that there will be much less need for technical writers in the future.

 For now, though, I have happy freedom from writing a lot of procedures. I never am compelled to restate the obvious (“Type your name in the Name box”). A lot of my help topics seek simply to point out features or navigational elements, to provide a quick, visual orentation to a page in the interface. It lets me take advantage of one of my most strongly held beliefs: never use words when you can use a graphic.

This brings some challenges, however, and I welcome your thoughts in the comments section.

1) There is a problem with consistency. I can treat some topics graphically, but in reality some do still require procedures. Is that a problem?

2) Right now, I’m using SnagIt to capture and edit the screenshots. Obviously, they’re not editable in the doc or help file. You only get one chance to get the callouts correct. Is there a better tool/method?

3) Aesthetics: I welcome comments. The green is obnoxious, but you have to admit it’s easy to tell the callouts from the UI.

Handy list of tech writer blogs

Here’s a handy list of tech writer blogs. You can easily add your own blog to the list. I wish they would let you add a little blurb, because you can waste a lot of time clicking through the links only to find out that a given blog is un-interesting or irrelevant.

 It would even help if they’d let you characterize your blog as primarily ”informational”, “educational”, or “opinion”.

Broken: AT&T elevators

I wish I had a picture of this; if I did, I’d send it in to that website that has the broken user experiences (I can’t remember the name; help me out if you do).

 I recently visited the AT&T campus near Lenox Square here in Atlanta (to orient my international readers .)

They have a very nice building. Except for one thing. The elevator floor buttons are outside the elevators. So if you don’t remember to push the button of the floor you’re going to BEFORE you get in the elevator, you get to ride along with all the folks who did. But you don’t necessarily get to go to your floor.

A very broken user experience!

Irregardless: poster child for word/nonword debate

I really enjoy debating about words. I am  a word nerd. I offer the following in the spirit of debate and the love of technical writing. A recent mini-debate with Mike Hughes about the acceptability of the word “irregardless”, in the comments section on Holly Harkness’ blog has got me thinking, not just about that particular word, but about our responsibility – as tech writers – for word choice in general.

 

I spent several years frustrated by what I considered to be some unnecessary, old-school constraints required by my company’s style guide. Making progressive changes was like turning the Titanic around, because there were 11 writers (making consensus building a challenge in any case), several of whom were  “rear-brainers” as described by Mike in his blog.

Now I’m at a startup, and I’m happily free to buck the gatekeepers of grammatical purity (because there aren’t any here) and write any way I please, including using any word I want. I’m perfectly situated to pursue timely and relevant styles and words, but I don’t think that unequivocally accepting whatever the masses are doing to our language is the same as making progress in relevancy. I still truly believe that those of us who are good at English (and I’d hope all techwriters are) have a responsibility to set a good example.

I tried to think of a corollary to help explain how I feel. I’m very bad at math. I recently went to MIT Alumni Comedy night, which naturally has an audience heavy on mathletes. There were jokes about imaginary numbers and Platonic solids (yes, seriously; the mathletes laughed til they cried). As a result, I got some math info presented in an extremely engaging, casual way. But however casual the presentation, I do expect the actual math to be correct. When something is presented by an “expert”, people assume correctness and then model what they learned.

If we model low-quality writing for our readers by using words that are fundamentally incorrect or even illogical, such as “irregardless”, we can expect language to be continuously dumbed down. I don’t ever want to be the standard bearer of rigid adherence to rules and words that aren’t relevant to today’s audience, but I also don’t want to see technical communicators spreading least-common-denominator vocabulary of the wrong type.

 

I’ll blog on the right type of least-common-denominator vocabulary soon.

One extra note: I used to be a marketing copywriter. The ideas in this post are all wrong for them, so don’t extrapolate! I’m pretty sure there aren’t any rules in marketing copywriting, nor should there be! Here’s a marketing copywriting blog I love.It’s a very cynical, bitter, funny blog by a freelancer in Florida. He’s had some great posts about Obama branding lately. 

Welcome to my blog!

I really enjoy sharing ideas about emerging trends and existing standards in technical writing and other user experience activities. I hope that you will feel free to contribute comments and participate in healthy debate. I’ll also post links to internet resources I find helpful or amusing.