Dealing with the Documentation Aspects of Bad Software -- My Response to the Latest DMN Communications Podcast

by Tom Johnson on Jan 25, 2007
categories: technical-writing

I just listened to the latest podcast from DMN Communications. In it, Scott and Aaron talk about how to deal with documenting bad software. They asked for listener feedback, so I'd like to offer my opinion.

First let me explain their question. They ask what you should do when the application you're documenting is backwards and non-intuitive, and your suggestions for UI and other design changes have been disregarded.

Scott and Aaron explain your options at this point:

You are faced with an ugly reality - you are going to have to document software that is considered sub-par in conception/design/analysis/execution/all of the above. ... You are going to have to go the extra mile and log extra hours because of the extra effort required to elegantly communicate how to use an inelegant solution. For example, you'll probably have to spend extra time structuring information in order to accommodate procedures that have a less than logical flow. Or you will have to include more screen shots than normal to illustrate a process or task. You will likely spend more time with development asking questions and clarifying functionality. The fact is, you really have to care about a product at this point.

They mention several courses of action — lobbying for better design, making a case for the financial cost of bad design, just documenting the application anyway and ignoring the bad design, and finally, leaving.

The last option is to get out of there. If you don't care, then you're job's going to be a chore and you're going to be unhappy. Your unhappiness will really reflect in your work. There's no shame in cutting your losses and running. I know, that sounds harsh. But that's the reality of things from my perspective. If you're a professional, you take pride in your work. If you can't do that, you need to find something else.

I agree that the technical writer should be a user advocate and put up a fight for a good design. But sometimes technical limitations require awkward processes. And sometimes developers are just ignorant about usability and stubborn with their creations.

But even though the application may be unintuitive, I think this usability-handicap only enlarges the importance of the help file and the role of the technical writer. Suddenly the user is really going to have to check out your help file! You're now an important player in the success of the product, because without your clear, crisp instructions, the users will be lost.

I kind of like that feeling.

Now granted, job security at the expense of usability is not what I'm advocating. I'm just saying that if you've done everything you can do for usability, take pride in knowing that your role as a technical communicator can sometimes be extremely important. I wouldn't walk away from the project. (Heck, I'm not so financially set that I could walk away even if I wanted to!)

Thanks for the great podcast, Aaron and Scott. Their blog is here: http://www.dmncommunications.com/weblog/