RE: Task-based versus UI-based documentation

[Mike Starr <mike -at- writestarr -dot- com>]

I consider UI-based documentation a subset of reference-based documentation.

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/


> Date: Mon, 11 Aug 2014 15:53:04 -0400
> Subject: Re: Task-based versus UI-based documentation
> From: jstickler -at- gmail -dot- com
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> 
> 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 mike -at- writestarr -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

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

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