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.
Tara English-Sweeney produces quick reference cards that <<... have served
multiple purposes in the past - (1) as a way to distribute documentation
about new features that weren't covered in the manuals, (2) as installation
guides, and (3) as standard quick reference cards. We are about to revamp
them. They've become little clones of our manuals (they're too long!)>>
Sounds like you've lost sight of the goal of the material, or at least
forgotten the "quick" part of "quick reference".
<<many people recommended knowing your audience or performing user tests.
And, we will certainly follow those suggestions [... The timing is perfect
as I'll be at a conference for our users the rest of this week :)].>>
And that recommendation can't be repeated often enough, since it's so
obvious that few seem to remember to do it. The only people who can tell you
what _they_ want in a QRC are the people who will use it.
<<Our software is aimed at IT administrators. And, it's complex. We will be
meeting next week to try to determine where to draw the line on information
included in a Quick Reference Card (QRC). I think it's a given that we'll
include descriptions of the main icons, menus and windows/dialog boxes.>>
Providing a visual reference is an excellent idea, particularly if you match
it to the screen display so users can rapidly find what they're looking for;
long lists of icons are meaningless because there's no obvious visual sort
order (e.g., does the letter icon come "alphabetically" [sic] before the
trashcan or after it?). Figure out what proportion of the reference
information should be built into the interface itself, since the best way to
make complexity manageable is to combine the task with the reference
material that directly supports that task. Use affordances, contextual help,
logical sequencing, and other tricks that help users accomplish their tasks.
<<the real questions for us are about handling procedures and conceptual
information. Should basic procedures be included in a QRC? Should concepts
be left to the manuals?>>
QRCs generally shouldn't include procedures; that kind of task is much
better handled by a wizard (something that walks you through the process of
performing a task) or by the workflow itself. Reference material should be
available online, so that as soon as users encounter a step in a complex
process and want to know their options, they hit the help button and get the
information they need immediately. Concepts belong online if they explain
(say) a specific field or button, but belong in the manuals if the reader
will be using them to figure out how to approach a problem. (You can also
move this kind of information online, but it'll tend to be more usable if
the reader can learn what they're trying to do before ever entering
hand-to-hand combat with the software.)
<<How much is too much information? too little?>>
Respectively, "more than they need to accomplish a task" and "less than they
need to accomplish a task". They're the only ones who can tell you this
information.
"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer
