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.
I think the problems with Help that Kevin talks about here should be one
of the top pet peeves of any professional tech writer. Seems to me there
are many more examples of bad Help design/organization than good ones.
So many more that I now consider it a small miracle whenever I encounter
Help done right.
(Disclaimer: The intensity of my feeling on the subject may be due to
the fact that I'm currently working on a project that involves reading
owner's manuals from every automotive manufacturer on the planet.)
-Brian H.
-----Original Message----- From: Kevin McLauchlan
I think one of the things that I really like to see on Help pages is
orientation.
Too often, some random help page just jumps into its own little
procedure, with all kinds of unspoken (unwritten) assumptions about how
the user/reader got there, and why they need to do what they're being
told to do right now, and what they should already have done.
As someone who can occasionally be found on this list likes to say
(might be the title of his blog...) "Every page is page one."
It's not like a book that has Intro and flow and continuity. A person
entering help might enter it at any point, for a variety of reasons.
Useful help has to let them know that they are in the right place, as
well as tell them the actual steps to do what they came for... if it
turns out they've actually landed on the page they needed... and not one
that has a similar/related procedure, but which doesn't apply to their
actual situation... and might actually hurt their situation if they
don't clue-in in time.
So a help page that includes a procedure should provide the continuity
by saying explicitly where it assumes the reader is arriving from, and
maybe what steps they should already have taken or what state they (or
the product) should already be in, for the current help page to be
useful.
ON THE OTHER HAND... :) Your structure and visual conventions should
show an experienced reader where the meat starts, so they can quickly
skip over the orientation material, if it's old-hat to them, and they
just want a refresh on the particular steps of procedure XYZ.
One of the biggest problems I encounter with Help on the web (if only
Microsoft and Adobe and others were listening) is knowing enough
background to decide that I'm on the right page for what I need. I
usually arrive from a Google search, so the specific instructions on the
page I'm reading might be perfectly accurate and easy to follow... but
completely wrong for what I need to accomplish. Or, it might be
completely right, but it just sounds wrong, because it appears to be
talking about something different than what I thought was my problem or
task. Glue. Glue is good.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.
Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.
