Re: Task-based versus UI-based documentation

Subject: Re: Task-based versus UI-based documentation
From: Julie Stickler <jstickler -at- gmail -dot- com>
To: Technical Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 11 Aug 2014 15:53:04 -0400

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
>



--
Julie Stickler
http://heratech.wordpress.com/
Blogging about Agile and technical writing

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
Re: Task-based versus UI-based documentation: From: Mike Starr

Previous by Author: Re: Task-based versus UI-based documentation
Next by Author: Re: "Chinlish" or English? (Kyle Simmons)
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