RE. Technical reviews of online help?

Subject: RE. Technical reviews of online help?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "Techwr-L (E-mail)" <TECHWR-L -at- lists -dot- raycomm -dot- com>
Date: Tue, 23 May 2000 09:50:32 -0400

Cathy Arthur is <<... embarking on our first on-line help project... with
context sensitive stuff hooked into the program (a Windows based
application) by the programmers. There is a large project to be done, and I
am fairly certain I can persuade management to tackle a very small project
first to learn from.>>

Excellent idea. Work out the bugs using something simple, then use what
you've learned on the longer project. And use the opportunity to develop a
friendly, professional, helpful working relationshp with each of your team
members now, under relatively little pressure, before you have to find out
how they behave under lots of pressure.

<<One, the on-line help is developed and supplied to the technical reviewers
to view in their web browsers. This addresses the technical accuracy of each
topic, but will not address how appropriately or thoroughly the help is
integrated with the program.>>

If you can't get the help integrated with the software, this is a reasonable
approach. It's what I do early in the project whenever possible, and I give
them paper printouts so they can read the text and apply it to the screen to
ensure both say the same thing.

<<Second, we wait until the help is integrated with the program and hand the
entire thing over for review.>>

One thing that works well, depending on how well-managed your development
process is, would be to develop the skeleton of the help file before you
actually start work on the details. In effect, you give them just the
topics, along with the topic IDs, so they can link it directly to the
software. You now have the rest of the development process to test the links
and make sure that everything loads where and when it's supposed to load,
and that the help structure is efficient. (Ideally, the interface never
changes from this point on, but in reality, you'll still be doing tweaks
right up to when they ship. Make sure to include links testing late in the
development.) Later in development, as things change, at least you won't
have to worry too much about remapping topic IDs. The skeleton also serves
as an excellent planning tool because it's your contract with the
developers: "this is what we've agreed that I'll deliver". Bonus: You get to
complain about interface changes using the same childish tricks they do. <g>
("If you change this part of the interface, it'll take me at least a week to
redo that section of the online help. Why would you make me do all that
work?" <g>)

<<Lastly, do I print out the help topics, hand them over to the reviewers
(with the electronic version) and let them mark up the paper version?>>

That's a good idea no matter what you do with the online component. I've
been editing for nearly 15 years, and there are always things I catch on
paper that I miss onscreen.

<<I expect 2 or 3 reviewers. The company has not had a technical writer
before me (they relied on co-ops) so it is a
good opportunity to set up a robust review process.>>

Make sure you develop a good working relationship with your reviewers right
now, since that gives you a firm foundation to build on. Talk to each one
and find out how they differ in the ways that they prefer to work (e.g., one
of my developers answers every question I include in the printed docs; with
another, I have to talk him through each question if I'm to have any hope of
getting useful answers). Explain to them carefully just what you want them
to do, and make sure you've given them well-edited text to review (i.e., if
there are no stylistic issues for them to trip over, they're far more likely
to concentrate on the technical details, which is why you're asking them to
review the document). Discussing style issues (e.g., "click on the button"
vs. "click the button") before you start writing makes them feel that their
opinions are being considered, and gives you an important trump card later
in the process ("I'm not changing it because all four of us agreed last May
that this is the style we're using").

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"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

Previous by Author: RE. Graphics instead of words?
Next by Author: Re. Callouts for screen shots?
Previous by Thread: Lost softcopy - now what do we do
Next by Thread: Columns in RoboHelp Classic 2000?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads