Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,800+ subscribers. (See email archive here.)

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: http://www.dmncommunications.com/weblog/

Buy me a coffeeBuy me a coffee
Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,800+ subscribers. (See email archive here.)

follow us in feedly

About Tom Johnson

Tom Johnson

I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.

Comments
https://idratherbewriting.com/2007/01/25/dealing-with-the-documentation-aspects-of-bad-user-interfaces-my-response-to-the-latest-dmn-communications-podcast/
idratherbewriting.com
crawl=CC-MAIN-2021-43
47020
application/http; msgtype=response
sha1:HAFIX6TVR27GLFHX3S2B7OCJSL2BTULH
<urn:uuid:52a2842a-20bb-4cc3-b07e-7991a7d2ebd1>
2021-10-25T21:06:15Z
172.67.164.13
text/html
sha1:I3HTEJJITSGCLVVROJFDNBKHYLKVI5WQ
<urn:uuid:b25d6b87-7714-41e1-91d4-1d96899fa2e8>
https://idratherbewriting.com/2007/01/25/dealing-with-the-documentation-aspects-of-bad-user-interfaces-my-response-to-the-latest-dmn-communications-podcast/
response
<urn:uuid:6b7e9f50-f049-4e82-aad7-a65b15f739f2>
isPartOf: CC-MAIN-2021-43
publisher: Common Crawl
description: Wide crawl of the web for October 2021
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-67-67-191
software: Apache Nutch 1.18 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 1.2-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: https://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/