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: Display, Displays, or Appears? (take II) From:Geoff Hart <ghart -at- videotron -dot- ca> To:techwr-l List <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Thu, 05 Jun 2008 17:01:05 -0400
Jim Shaeffer notes: << I am loathe to quibble with anything that
Geoff says, but when he says: "If the software fails to behave
properly, describing what they should be seeing -- but are not
seeing -- is frustrating at best, and intimidating or infuriating at
worst." I wonder, is it not risking more trouble if the software
does not behave as expected, but the user blithely tries to perform
the remaining steps in the procedure?>>
Don't loathe the quibble. In intelligent debate are interesting
things revealed, including my imprecisions and malfeasance and
occasional outright ignorance. <g>
<<I would frequently cop out by writing something like: To framject
the ubi: 1. Click the Ubi button to access the Ubi Dialog box...>>
That works just fine, and indeed, I've done just that. Alternatively,
I've used the imperative form: "Display the Ubi dialog box by
clicking..." That's actually a good way to slip in the context and
make it explicit without seeming to be doing so. Some day I'd love to
have time to test these various variants to see which ones work best
in practice, not just in theory.
Leonard Porello noted: <<As I recall, Minimalist theory suggests that
results should be included only when needed for error mitigation.>>
I was using "minimalist" in the generic sense, namely that of
minimizing the number of words without sacrificing clarity. Your
recall fits with my recollection, though it's been a while since I
looked into this. I also have a memory that minimalist theory, sensu
John Carroll, is more about learning than about doing; that is, it's
designed around the notion of tutorials that encourage exploration
and learning by trial and error rather than bread-and-butter
procedural information. Treat that memory as suspect until confirmed...
Milan Davidovic wondered: <<1. Click A. 2. Select C. If C is
unavailable to be selected, then the reader knows something is wrong;
we don't need to say "The B dialog box appears" in Step 1. Correct?>>
That works for me. Of course, we haven't really tried to nail down
the role of context in this discussion. Some contexts require more
handholding and more explicit statement of the results than others.
I'm not sure there's an easy way to define which is which.
In a similar vein, Deborah Hemstreet noted: <<I think that the
redundancy is possible - but it depends on who your user is, as well
as the complexity of the system. That is why I usually place results
of an action on an indented unbulleted line under the action command.
The reader can quickly jump to 1 > 2 > 3 and get the job done - but
people who are struggling with what/how/when/where will get the
additional "redundant" information.>>
Very much so. It's a good way to layer information, particularly in
print (where you can't do expanding/collapsing views of the content).
I believe information mapping uses this approach to good effect, but
again, it's been a few years.
-- Geoff Hart
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
***Now available*** _Effective onscreen editing_
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-