Search results

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

dmn communicationsI 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:

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.