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: Help help From:mlist -at- safenet-inc -dot- com To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Tue, 4 Apr 2006 16:51:48 -0400
John Garison [mailto:john -at- garisons -dot- com] noted:
[...]
> But of there's one key idea that you need to get your head around, I
> suggest it's this: Links are free. If you create a whole
> bunch of topics
> that, when taken together, provide all the information necessary to
> describe the application, you are then free to create a
> series of other
> pages that provide links to these topics. As a result, you can provide
> role-based, experience-based, chronological, or hierarchical
> organizations that all consist of links to the individual topic pages.
> Within the topic pages themselves, you should link to related
> topics to
> make it easy for users to read and jump around in whatever fashion
> appeals to them.
I've encountered "Help" like that. Every time I try to actually
find an explanation or instruction for something specific that
I really, really need, I land on the damn description page.
I'm looking for a specific thing, a specific instruction, a
specific solution to the problem that I'm having right now,
and I keep circling through all these links and keywords that
keep dropping me back into the same few unhelpful pages. Aaargh!
If the answer to most questions and non-standard usage problems
is: Quit now, you're screwed anyway
then tell me that. Please don't dump me into the "all links
lead to the same 10 pages" equivalent of voice-mail hell.
That said, my first Help iteration for a new product might
have some of that, but after it's been in use for a while
and we've accumulated some questions and complaints and
use-cases, I try to have specific pages that answer specific
questions and cover what real customers have tried to do.
The cross-linking from _those_ pages is back to the more
general instruction, as well as to the descriptive concept
pages and to the command-syntax and reference pages... and if
I'm dilligent, all those pages eventually also have links
_to_ the growing array of specific and peculiar and less-often
used pages.
In some cases, I might have material repeated on a few pages,
using slightly different words or assumptions, in hopes that
a different way of saying/describing something will resonate
with a reader who might be from a different background or
market than the one(s) we originally envisioned.
For example, most of the descriptions and examples might
have related to (say) government data security, identification
and non-repudiation, but we start selling to big EFT customers.
They don't relate to the government-ish references, so I give
them examples or explanations using terms and scenarios from
the banking and clearing-house world.
Sometimes I might be creating almost redundant pages, for
people from different backgrounds to DO something. Other times,
I might have created alternate descriptions or drop-downs or
pop-ups to let whole classes of customers know that they
can ignore this or that command, or Admin/Maintenance procedure,
because, while the appliance supports a function, it doesn't
really apply to how they (the particular user group) use
the product.
Kevin
The information contained in this electronic mail transmission may be privileged and confidential, and therefore, protected from disclosure. If you have received this communication in error, please notify us immediately by replying to this message and deleting it from your computer without copying or disclosing it.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
