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.
Kathleen responded to my previous post: <<So would it be a fair summary
to say that you're saying angle brackets are ok only when writing for
the experienced user?>>
Not "only". And I'm by no means saying that inexperienced readers are
unable to figure this out, but rather that you're adding one more task
to their cumulative cognitive load. Since you don't know the "tipping
point" at which that load becomes so high they'll abandon your
documentation, it's better to avoid that load in the first place.
<<How quickly we forget: I can remember when I first encountered the
angle brackets: I thought they were horribly uninstructive and
unintuitive but used them because that was the style in place.>>
This is exactly the kind of thing I'm getting at. Most experienced
techwhirlers have long since forgotten what it's like to be new to a
concept, and assume that because something is intuitive to them, it
will be intuitive to their audience. I suspect (no statistics) that
this is the primary cause of failed documentation.
<<OTOH, when writing a manual, the angle brackets could be introduced
along with more formal instructions for the most basic actions, which
it could be assumed that novices would be using. So the novice would
gradually learn their meaning.>>
That's an interesting suggestion. If, for the sake of argument, you
were able to determine what parts of the online help or printed
documentation each new user will encounter within the first few days of
using the product, you could build this instruction into those parts of
the documentation, thereby ensuring everyone would learn the
convention.
Sue Gallagher "completely disagreed", as we're wont to do--and
generally much light emerges from the heat generated thereby. <g> <<One
of the most frequent complaints I hear from neophyte software users is
that there's too much to read. Users get lost in a sea of extraneous
words and can't find the important keys burried in the text. And
frequently, the complaint is that there's so much attention paid to the
"point here, click this" instructions that the concepts the user really
needs to learn are obfuscated.>>
By my definition, that's bad writing and poor design, not a problem
related to writing out the commands vs. using cryptic shortcuts. I'd be
curious to hear your statistics: such reports are anecdotal, and while
that doesn't invalidate them by any means, hard numbers make a far more
convincing case.
<<Please remember that New User != (does not equal) Stupid User.>>
See above. It's not about stupidity, but rather about easing the user's
burden. If you do that well, the docs work well for everyone.
David Neeley also disagreed: <<If you are writing for the totally
clueless, a screen capture of the actual menus next to the "shorthand"
of the angle brackets the first few times will surely get the point
across.>>
Actually, several years of the latest research out of the Netherlands
demonstrate convincingly that annotated screenshots are far more
effective than text-only solutions for all users, including experienced
ones. The problem with "first few times" is that although this works
great in instructor-led education, where you can control what
information students see and in what order, it fails when you cannot
ensure that your audience will read the "first few times" you present
something. I believe Scott DeLoach has good statistics on users turning
away from Help systems and never returning when they encounter
something difficult or offputting.
Speaking of anecdotal evidence, I can confirm the effectiveness of the
graphics plus text approach from firsthand experience, in the context
of a quick-start user guide destined for use by computerphobes and
neophtyes--all of whom were quite bright, but completely paralyzed when
they confronted complexity: I combined explanatory text with menu shots
and photos of the hardware, and essentially eliminated tech support
calls. Our single support tech was very grateful, as you can imagine,
and went out of his way to work with me on future docs, which was a no
less important success imho.
Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today! http://www.webworks.com/techwr-l
Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author
content and configure Help in MS Word or any HTML editor. No
proprietary editor! *August release. http://www.componentone.com/TECHWRL/DocToHelp2005
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
