Re: Task-based versus UI-based documentation

Subject: Re: Task-based versus UI-based documentation
From: Mike Starr <mike -at- writestarr -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Fri, 08 Aug 2014 17:50:44 -0500

David Artman and I agree... here's my take on it.

This is a draft of an article I've been tinkering with for my website wherein I nail another sheaf of papers on the door of the technical writing cathedral. I've got the sneaking suspicion that the graphic won't show up. If it doesn't you may see it at http://www.writestarr.com/DialogBox-PSP-DecreaseColorDepth.png

The current received wisdom within the technical writing community is that we must focus on task-based documentation... give the users instructions for the most common tasks they might want to perform. Overall, I agree with the need to provide task-based documentation but I disagree vehemently with the position that we don't need to provide reference-based documentation. I strongly believe that good documentation (and I define good documentation as what serves the user best) includes both task-based documentation and reference-based documentation.

Let me give you an example. I'm very persnickety about my screen captures. I do my best to tweak them so that if a user should decide to print a page that contains a screen capture, it looks good in print as well as on the screen. In spite of the fact that I'm currently using Windows 7, I use the classic Windows theme and eliminate the gradient from the title bar. I also turn off the Windows ClearType functionality so that all the text is a solid color rather than a motley mix of colors that's impossible to change easily. One of the tasks I've performed many times in the past was using Jasc Paint Shop Pro 9 to decrease the color depth of an image, applying the standard Windows 16-color palette.

If I were documenting the procedure in a task-based manual or help system, I'd do something like this:

/====================================================/

Follow these steps to decrease the color depth of your image, applying the standard Windows 16-color palette:

1. Choose the /Image>>Decrease Color Depth>>16 Colors (4 bit).../ menu
item.
2. PSP displays a /Decrease Color Depth - 16 Colors/ dialog box similar
to the one shown here.
DialogBox-PSP-DecreaseColorDepth
<http://writestarr.com/wordpress/?attachment_id=123>
3. In the /Palette/ frame, choose the /Windows/ option button.
4. In the /Reduction Method/ frame, choose the /Nearest Color/ option
button.
5. Click /OK/ to apply your changes and dismiss the /Decrease Color
Depth - 16 Colors/ dialog box.

/====================================================/

Okay, that does the job nicely; we've taught the user how to do the task he or she set out to do. However, now that we've exposed the user to the /Decrease Color Depth - 16 Colors/ dialog box, the user is likely to say "Hmmm... I wonder what happens if instead of choosing the /Windows/ option button in the /Palette/ frame, I choose the /Optimized Median Cut/ option button. I'll click the /Help/ button." Imagine the user's dismay when the help screen comes up and there's nothing but the hundred or so most common tasks presented as product documentation, none of which offers any explanation of what the /Optimized Median Cut/ option button means.

When we're dealing with complex and powerful products, we need to help the user understand all the options the product contains and we just can't do that if we limit ourselves to task-based documentation. In the dialog box above, there are 13 buttons, two sets of option buttons (three each), and two checkboxes, one of which has a numerical adjustment control. The documentation we provide to the user has to give a way of finding out what the controls on this dialog box can do and when one might want to deviate from the selections made in the procedure I've given above. If we don't they're going to call the help desk or send an email to the support group and that's going to cost our employer money to deal with. Yes, it does cost more to pay technical writers to develop such comprehensive documentation but the better the documentation we provide, the greater the reduction in support costs. It pays for itself in the long run. Our documentation needs to provide a solid mix of both task-based documentation and reference-based documentation.

/Note:/ The help system that comes with Jasc Paint Shop Pro 9 is very comprehensive and does contain descriptions of all controls on all available dialog boxes. It's a model for me of good documentation for a complex and powerful product. Paint Shop Pro (PSP) is now owned by Corel and is currently at version 15 but I'm well satisfied with version 9 and continue to use it.

Best Regards,

Mike
--
Mike Starr, Writer
Technical Writer - Online Help Developer - WordPress Websites
Graphic Designer - Desktop Publisher - Custom Microsoft Word templates
(262) 694-1028 - mike -at- writestarr -dot- com - http://www.writestarr.com
President - Working Writers of Wisconsin http://www.workingwriters.org/


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

References:
RE: Task-based versus UI-based documentation: From: David Artman

Previous by Author: RE: Task-based versus UI-based documentation
Next by Author: RE: Task-based versus UI-based documentation
Previous by Thread: RE: Task-based versus UI-based documentation
Next by Thread: Re: Task-based versus UI-based documentation


What this post helpful? Share it with friends and colleagues:


Sponsored Ads