RE: Task-based versus UI-based documentation

Subject: RE: Task-based versus UI-based documentation
From: "David Artman" <david -at- davidartman -dot- com>
To: "Cardimon, Craig" <ccardimon -at- M-S-G -dot- com>, "'TechWR-L'" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 08 Aug 2014 12:29:08 -0700

Both and more:

1) Conceptual overview to address general workflow, important terms and
relationships of features, and a high-level orientation to the UI.

2) Reference content to provide a 'map' (if you will) of the UI
comprehensively. Callouts of same to tie concepts into tasks (i.e.,
definition of control, followed by xrefs to tasks which often use it).

3) Task content to address, in order of occurrence or frequency, actual
steps and processes and gotchas. Minimal screen captures or UI
orientation in them, except to xref to the Reference content when it
might be unclear (e.g., multiple controls with similar names on the
same screen, NOT showing a message box to tell them to click OK).



A combination of that content can create:

* Quick Start Guides

* Executive overview and feature list (and changes lists)

* Operational training material

* Training reference material (i.e., "Cheat sheets").

* Comprehensive User Guides (and sub-variations: Admin Guides,
Programming Guides, customer-specific variations of all, etc).



If your budget is so tight as to only allow a subset of 1-3, I'd do 1
and 2 and leave 3 as an exercise for the reader (i.e., something to
train and practice). That's tantamount to providing a rule system and a
map, but not telling them strategy or fastpaths.



ALL that said... I tend to document insanely complex software, the past
decade or so; and so it's pretty rare that a "how to do foo" task
directive can be made sufficient to even a plurality of users, never
mind a large majority (and forget about all: exceptions are the rule,
here!).



HTH;

David

-------- Original Message --------
Subject: Task-based versus UI-based documentation
From: "Cardimon, Craig" <[1]ccardimon -at- M-S-G -dot- com>
Date: Thu, August 07, 2014 7:59 am
To: 'TechWR-L' [2]techwr-l -at- lists -dot- techwr-l -dot- com

What method do the TechWhirlers prefer: Task-based or UI-based
documentation?

References

1. mailto:ccardimon -at- M-S-G -dot- com
2. mailto:techwr-l -at- lists -dot- techwr-l -dot- com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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:

Previous by Author: Re: Use of the word "doubt"
Next by Author: RE: How to mention usernames and passwords
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