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.
Brant Bangeman reported <<My company likes to include a
quick start guide with each new software update. The guides
run ten to fifteen pages for each update and are created
directly from the help file. I wouldn't consider a fifteen page
(including screen shots) document "quick" to read.>>
"Quick" is an extremely subjective word, and page counts are
probably the least useful criterion for whether something is
quick to read. More importantly, "created directly from the
help file" sends up a warning flag, unless you spend a fair bit
of time customizing that information to suit its new role in life
(tutorial rather than reference). Personally, I like nothing
better than a concise 15-page introduction that tells me what
the product can do, where the tools are located for these
functions, and where to look in the main manual for more
detailed information. And personally, I'd happily devour
those 15 pages so I can acquire the context I need to
understand whether I have to read further, or can just dive in
and start playing. It's an awfully small investment of time,
with huge payback in some cases.
<<Most of the information applies to novice users. I don't
have much experience creating documentation; however, I
believe the guide should be short and to the point without a
screen shot for each interface.>>
As always, "what works" depends entirely on your audience.
Stating that they're novices is largely irrelevant, because that
tells you only that you can't leave important details implicit
and can't dive right into the jargon; it doesn't tell you whether
they understand the basic metaphor for the product, or what
the product is intended to do, among other things. Find out
what their needs are, and focus on those.
<<What about using a PowerPoint presentation?>>
I detest online presentations because they're generally not
interactive and don't let me see (or play with) the application
while the presentation is running. If you can come up with
something like an interactive wizard that explains the concept
and then lets the user try it out, that would be far more
effective... at least for the type of user who "learns by doing"
rather than "learning by reading". I flipflop between the two
learning styles, and I suspect most people do too, at least to
some extent. Maybe you can do both a presentation and the
quickstart guide?
