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.
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").
"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
