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.
>>Is it as simple as having additional links at the bottom of the page that opens when the user clicks [F1] while a dialog is open?
>>Or do y'all have more sophisticated strategies? What might some of those be?
>Hoo, what a question . It's both.
> We spend as much time as we can "sitting next to the user" so we know what they ask.
I see you put that in scare-quotes.
Are your end-users actually accessible to you in some way?
Or do you do what I do, constructing a composite
"user" (or three) from field trouble reports, Sales-Engineer
discussions, Apps-Eng/Engineering-Services comments
and discussion threads?
I also do my own using/learning of each product release,
and spend much time with the engineering testers,
but they are already extremely knowledgeable, so
while they are a big help at learning new functions
and features and some of their implications, they
aren't much help in getting a feel for what a naive
user requires.
Any new tester, and many new developers, as they
come in, get nabbed to be guinnea-pigs for my docs.
It helps them get up to speed on our products, and
it helps me to see where the docs might be thin or
too voluble or missing something or broken. But we
aren't hiring somebody every month at theis branch
office, so...
> From that, we derive the "top user tasks" that people have questions about, that are not obvious in the software.
Aside from the basic "everybody has to do this" setup/configuration
and maintenance tasks, we are constantly learning new "top user
tasks" as our products enter new and varied markets.
> Each of those has a topic about it, and each topic involves one or more dialog F1s.
> the dialog F1 help has the additional links to the task topic(s) (not always at the bottom, depends on relative importance)
But of course, you also have ToC, glossary, Index,
and Search for the general and background info
(for me that's about half of the entire Help for
a product - but then we don't have a GUI, so we're
not yet "context sensitive").
> The big deal is to document only what they have questions about.
> If the GUI makes the information obvious, we don't put it in the help, it only gets in the way.
I wonder if all classes of user-customers would agree on
what is "obvious".
We sell to (among others) end-users of widely-used
third-party apps (in the crypto space),
so there's a fair bit of control in that situation
regarding what the end-users know, what they expect,
and how they talk about this-or-that topic or activity.
But we also sell to developers, and-or to the people
to whom they sell their products and services, and
there is where a lot of variety and latitude creeps
in with respect to end-user knowledge, the kind of
industry (and industry terminology) they know, what
they want to do, how much or how little training or
exposure they've had, whether their industry is
mature and has stable standards, or is so new that
the word 'standard' elicits smiles and winks and a
week without at least two neologisms was a slow week.
:-)
> We work with the GUI team to make sure labels are descriptive and have examples
> so even if we do have to have a dialog F1 that talks about field names, it's only because the field names
> are more complex and interesting than can fit on the UI itself.
I'm fortunate in that there is - and will tend to
be - a divide between the concepts and config/admin/
housekeeping tasks that I need to document, and the
tasks that are done (with our stuff) by a third-party
app.
We might eventually need to give our Help a
variable look-and-feel to make it fit in with
a third-party vendor's offering. But that's a
while off. (By "a third-party vendor", I mean
any of dozens, though we'd likely start with
one of the biggies and see how that went.)
Is anybody doing that now? Producing "generic"
help for your product, but assisting your big
customers to adapt/integrate that help into the
larger Help that they provide for their product
(of which your product then becomes a component...) ??
- K
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.
Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and
produce desktop, Web, or print deliverables. Just write (or import)
and Doc-To-Help does the rest. Free trial: http://www.doctohelp.com
- Use this space to communicate with TECHWR-L readers -
- Contact admin -at- techwr-l -dot- com for more information -
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
