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.
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?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l
