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.
Mike Starr wrote
> I disagree vehemently with the position that we don't need to provide
reference-based documentation.
When did anyone suggest that you don't need reference topics when you're
writing task based documentation? Did I miss that?
I always supply reference information and the occasional UI topic
(disguised as a Navigation overview) when I write what is predominantly
task based documentation.
On Fri, Aug 8, 2014 at 6:50 PM, Mike Starr <mike -at- writestarr -dot- com> wrote:
> 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 jstickler -at- gmail -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
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l
