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.
Subject:Re: RE: my bad displays habit From:Odile Sullivan-Tarazi <odile -at- mindspring -dot- com> To:John Posada <jposada99 -at- gmail -dot- com> Date:Tue, 2 Mar 2010 11:12:16 -0800
What we do, rather than including a separate results line, is locate
the user in that new UI at the beginning of the step that follows.
That is, rather than this format --
1. Do this.
The Such and Such dialog/wizard/window appears/opens.
2. Do that.
something more like this --
1. Do this.
2. In the Such and Such dialog, do that.
The dreaded "appears" line does not continually appear (enabling us
to better use that space for other commentary), and the user is
always located in new UI at the beginning of the step in which action
is to be taken in that UI.
If the location does not change in subsequent steps, that location is
not renamed. But if a new dialog or window or whatever appears, and
if the user is to take some action in that UI, then that new location
is again cited at the beginning of the first step in which the user
undertakes a task in that new location.
Thus, in this example if Step 3 were undertaken in the same dialog,
it would simply read "Do something" (that is, it would consist only
of the task, not the location). If that action were to open another
window, then Step 4 would read "In the Such and Such window, do
If at any point the user is returned to a previous location -- she's
in dialog A for a few steps, say, and then in dialog B for a few,
then (having finished and closed that dialog) she is again in dialog
A -- the location is restated.
Basically, whenever the location changes (whether it is an entirely
new location in the procedure or one returned to), it appears at the
beginning of the step. Otherwise, the step begins with the task, and
the user can assume the same location.
That's the general idea. Naturally, if something unusual happens, we
use some version of the "appears" line.
It seems to work fairly well for us. We have procedures that can
involve a lot of changes in location: wizards, dialogs, various
editors and palettes, property inspectors, and so on. Putting the
"appears" line in there really lards the procedure with a lot of text
and space, and we wouldn't want to follow a space-saving strategy
that involved routinely including it in some cases and not others.
We want always to alert users to a change in location, but
seamlessly, with few words and no interruption to flow.
Does anyone else follow a style like this? Our audience is
technical, which helps, but I don't think what we're doing would
throw end users (except perhaps the very novice). And, to weigh in
on this issue of "surprise," though our users are technical -- though
they are fully aware that they'll be surfing through various pieces
of UI -- we are always mindful of locating them precisely in that UI.
It provides quick feedback to confirm that what they're seeing, and
where they're landing, is correct.
At 1:32 PM -0500 3/2/10, John Posada wrote:
>I'm in the camp of including the results.
>It's not that my users are surprised that "something" displays...it's
>that I want them to know that the right thing displayed.
>The way I see it, if you don't tell them what should be displayed,
>then ANYTHING that displays is the correct thing to display.
>On Fri, Feb 26, 2010 at 6:05 PM, Gene Kim-Eng <techwr -at- genek -dot- com> wrote:
>> I wrote user docs like that 25 years ago when half my readers were
>>likely to be people who were staring at the first GUI they'd ever
>>seen, but is there anyone left today who's surprised when clicking
>>on something brings up a window, or even contemplates the
>>possibility that they've gotten the wrong one?
>Senior Technical Writer
>NYMetro STC President
>Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and
>produce desktop, Web, or print deliverables. Just write (or import)
>and Doc-To-Help does the rest. Free trial: http://www.doctohelp.com
>Explore CAREER options and paths related to Technical Writing,
>learn to create SOFTWARE REQUIREMENTS documents, and
>get tips on FUNCTIONAL SPECIFICATION best practices. Free at:
>You are currently subscribed to TECHWR-L as odile -at- mindspring -dot- com -dot-
>To unsubscribe send a blank email to
>techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
>To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
>Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
>http://www.techwr-l.com/ for more resources and info.
>Please move off-topic discussions to the Chat list, at:
Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and
produce desktop, Web, or print deliverables. Just write (or import)
and Doc-To-Help does the rest. Free trial: http://www.doctohelp.com
Explore CAREER options and paths related to Technical Writing,
learn to create SOFTWARE REQUIREMENTS documents, and
get tips on FUNCTIONAL SPECIFICATION best practices. Free at: http://www.ModernAnalyst.com
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-