Rhonda Bracey: At Random

Last week I created a technical writing bookstore, and today I added some more items – some software that I use, a couple more books, and some miscellaneous recommendations. Check out the new additions here: http://astore.amazon.com/cybertconsul-20/002-3075581-1356021

I received a lovely pile of books from Amazon the other day (oh goody! Christmas already!) and figured I may as well join up with their Associates program again. (Aside: Way back in another life -1996? – when I was working as a captive employee, we joined Amazon Associates, but it was so new and so early in web development that it didn’t really fly. Anyhow, that episode in my life is a story for another time…)

The books I received were some I couldn’t get here in Australia, and some were just so cheap compared to local prices (even including freight) that it was a no-brainer to buy them from Amazon. Much as I’d love to support Australian companies, when the difference is more than $100 AUD you start to think more globally.

The upshot of all that is that I figured other technical writers might like a synthesized list of what’s on *my* tech writing bookshelf. So I created an Amazon store for my recommendations. You can visit it here: http://astore.amazon.com/cybertconsul-20/
BTW, *any* item you purchase from Amazon after linking via my store, brings me a dollar or two. No difference to you – you still pay the normal Amazon price – but I get a small percentage.

We’ll see how it goes…

Tags: technical writer, technical writing, technical communication, technical communicator, tech writing, tech writer, online help, documentation, books for technical writers…

Finally, a long term 3-day-a-week technical writing contract that I’ve had for some five and a half years will be coming to an end towards the end of June. I’ve known this for ages, but it’s only recently that they found a full-time replacement for me. Since a date has been set for my replacement starting and me doing a handover week, it’s amazing how many other doors are opening without me actively looking.

I’ve had several phone calls this past week, all of which are potential contract opportunities. Of course, nothing may come of any of them, but as I haven’t had many work calls in the past few months, I’ve got to wonder if it’s the state of the economy at the moment, or … [cue “Twilight Zone” music here] … something more universal in that I’m *allowing* myself to be open to new possibilities. Oh well, whatever…

Last week a discussion on one of my tech writing lists focused on using fictitious names in documentation, such as in Name fields in software and websites that are used in training, demonstrations, and screenshots in the manuals. One thing you don’t want to do is use a set of real names from a real client. In fact, I heard of an instance – it may be an apocryphal tale – where a real person’s name was projected on a large screen, and some in the training session got very upset as that person had died very recently.

So this discussion offered some ideas for ‘dummy’ names that you could use. Now, whether you would actually use any of these is not my call – you’d have to make your own decision based on who you work for and who your audience is!

Here’s a sample of some that were offered:

If you need ‘real’ names, you can always try some of the many random name generators on the internet. You can get some very weird ones (like Klingon names, fantasy names, etc.), but there are ‘real’ names among all that too. One that I particularly like takes the names from the various US census and mixes them up according to popularity, gender, etc. Try it at: http://www.kleimo.com/random/name.cfm (another one I found when looking for this one was:
http://www.behindthename.com/random/)

(Thanks to the contributors on the STC Lone Writers discussion list)

Today, on one of my tech writer lists, someone posted a link to this website where the rules of Klingon tech writing are documented.

In case this list ever disappears, gets moved, whatever, I’ve reproduced it here, with thanks to whoever put it together! (My favourite is #4.)

Klingon Technical Writers
The top 16 things likely to be overheard if you had Klingon technical writers working on your documentation team:

1. Klingons do not sit in meetings, we take what we want and kill anyone who opposes us!
2. Certification?! Taking your head and putting it on a pike in my office is all the certification I need!
3. I will return to the homeworld and my documentation will arise triumphant in the STC Documentation Gauntlet, leaving all others drowning in their own dangling modifiers. It will be glorious!!
4. Not returning my review copies by the agreed deadline is a declaration of war. Indeed, it is a good day to die.
5. These software specifications are for the weak and timid!!
6. This version of Word is a piece of GAGH! I need the latest version of Framemaker if I am to do battle with this manual.
7. You cannot really appreciate Dilbert unless you’ve read it in the original Klingon.
8. Indentation?! I will show you how to indent when I indent your skull!
9. What is this talk of “drafts”? Klingons do not make document “drafts”. Our documents escape, leaving a bloody trail of SMEs in its wake!
10. Passive voice is a sign of weakness. Its elimination will be quick.
11. Proofreading? Klingons do not proofread. Our documents are purified with pain-sticks which cleanses the documents of impurities.
12. I have challenged the entire Marketing and R&D team to a Bat-Leh contest! They will not concern us again.
13. A TRUE Klingon warrior riddles his document with bullets, leaving it to beg for mercy.
14. By changing the layout of my manual, you have challenged the honor of my family. Prepare to die!
15. You question the worthiness of my grammar? I should kill you where you stand!
16. Our users will know fear and cower before our suite of manuals and online help! Ship it! Ship it and let them flee like the dogs they are!

… I don’t think so!

David Pogue, the NY Times technology guru/columnist had something to say about the complexities in setting up a home network, but really it was a rant about the overblown “Wizard” he was faced with when trying to install some Netgear hardware.

One reading his post, it sounds as though everyone from the developers to the lawyers had input into the Wizard – everyone, that is, except the tech writer or “user experience” (UX) expert! An hour of the tech writer or UX person’s time could have dramatically improved this Wizard… such a small price to pay – and much cheaper than lawyers!

(a.k.a. wordsmiths)

After work today we had our informal get together of the local tech writers group at a pub in Subiaco. Much wit and repartee and some terrible puns! Puns we couldn’t get away with in normal conversation with work colleagues or friends and family, but puns that had the appropriate level of groan response with that group.

Thanks guys – it was fun swimming with my own kind again.

Warning: long!

I mainly work for software companies. And so far none of those companies have employed a usability expert. As the person who is the ‘user advocate’ when writing the documentation, I’ve worn the ‘she’s the usability person’ hat in the absence of anyone else stepping up to champion for readable labels, helpful screen messages, logical workflows in the interface, etc.

Ideally, usability specialists should be brought in at the initial design stage, then as the coding progresses, right through to release and beyond. Amongst other things, usability testing involves identifying areas where users of the software can get confused, then offering suggestions for fixing these BEFORE the software gets released. Fixes could include redesigning a screen, changing the text on a label, fixing a bug, and so on.

Such fixes cost far less when done before release than after the product has gone out the door. After release, the cost of fixing usability problems is much higher because implementing and testing patches, answering support calls related to things that don’t work as they are expected to, etc. all cost money. Then there’s the unquantifiable cost of user frustration – you know, the “I’d like to throw this bloody computer out the window!” situation I’m sure we’ve all experienced.

So, with that preamble, you can see that I’m very much on the side of making things as clear as possible for the users of the software. I’ve attended international conference sessions on usability, on writing useful error messages, etc. and I’ve worked with enough software in the past 20 years to have a clue about what expectations users have, and what can make their life a little easier. This is not ‘dumbing down’ the software application by any means – it’s about making it usable! Usable software usually garners passionate users (see Kathy Sierra’s great “Creating Passionate Users” blog for some terrific writing on this topic); unusable software tends to suck (to quote Kathy).

Last week when I returned to work, I had an email in my Inbox from the person responsible for testing (one of my clients actually has a dedicated tester – this is a good thing!). But I was completely GOBSMACKED by his response to one of my requests for a useful error message instead of the gobbledegook programmer-speak that was displayed. I won’t quote the request, or his complete response – I think you’ll get the gist of it in these couple of lines: “In my opinion trapping exceptions with … plain english dialogs is folly; a waste of developers’ time, a waste of development budget when there are more important things to do.”

I couldn’t believe it! My first response was jaw drop and eye pop and “what the??”; my second was to just throw it all in and walk out of there saying “Why do I bother?”; my third response was to think unkind thoughts about this person’s intelligence (but he’s an intelligent man); my fourth response – after I’d got over the initial shock – was to ask a respected colleague if he thought I was overreacting (he was equally gobsmacked, so I wasn’t overreacting); my next response was to IM a friend and colleague in the US to get her opinion to see if I was overreacting – she saw my full request and the full response and was equally appalled; my final response – after some hours of restraining myself – was to do a bit of research that showed that it’s not just me bleating about incomprehenisble error messages.

Here was the response I wrote (slightly edited):
====================
I stand by my assertion that ALL error messages in our applications should be useful and readable to the user – and that means plain English telling them what happened and, where possible, how to fix it.

Usable error messages have two main purposes:
* reduce user frustration with the application
* reduce support calls to whatever help desk exists (client’s or ours)

This is not “a folly” and a “waste of developers’ time”. It’s not even just my opinion – for example, see:
* http://www.useit.com/alertbox/20010624.html
* http://www.experoinc.com/resources/papers/2005-06-ErrorMsgs.htm
* “…Where possible, error messages [in Windows 2000] give users specific actions to take, rather than just informing them that something went wrong…” (from:
http://www.microsoft.com/windows2000/professional/evaluation/business/management.asp)
* http://www.eouroundtable.com/files/EOUupdatewp2000.pdf (page 9)
* “… Can the user recover from errors? What do users have to do to recover from errors? Does the product help users recover from errors? For example, does software present comprehensible, informative, non-threatening error messages? …” (from: http://en.wikipedia.org/wiki/Usability)

While I agree that fixing this error message in <current, almost superseded product> is not a good use of developers’ time at the moment, it is essential that error messages in <product to come> are in plain English and meet the basics of letting the user know what happened, why, and how to fix it (where possible). We’ll get much better and more satisfied users that way.
=================
The tester was away all last week, so I’ll see what sort of response I get back on Monday!

Two things this week that made my general day-to-day activities a bit different.

First, a friend in the US put me in touch with an author of a book on some software I use (was Macromedia’s Captivate; now owned by Adobe). The author wanted someone to co-write the update for v2 of this software (due out next month?), but unfortunately, after some to-ing and fro-ing via IM, I had to decline as the time frame was way too short. If I wasn’t already committed to 40 hours/week with existing contracts, I would’ve jumped at the chance. Not many dollars in writing books, but kudos can come in other ways! Maybe next time… (thanks Char!)

Second, I was asked to speak about my one-person business to a small group of undergrad students at Curtin Business School who are studying stuff on entrepreneurship. That was pretty neat and they asked some insightful questions. Thanks, Alicia.