TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
