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: Down Time From:Jean Weber <jean_weber -at- COMPUSERVE -dot- COM> Date:Thu, 5 Feb 1998 21:36:52 -0500
Vic Gemmingen asked,
>Here's the issue: What would you do to prepare for the task of creating
online help for an application that has yet to be created?<
Some suggestions --
1) Does your company have a style guide? If not, create one. If one exists,
does it need improvement? Does it cover online help?
2) Will you be involved in writing or reviewing the design of the new
product? If this isn't clear (or the answer is no), prepare and present a
case to <whoever> so you can be involved.
3) Get a *clear* understanding (and agreement) from the software developers
of how the help is going to be integrated with the product. A *big* issue
on several projects I've worked on has been -- the programmers can create a
screen that serves several (or many) purposes. The fields and controls that
appear for any one situation (purpose) vary from other situations. If the
screen has only one "resource ID" to which help can be attached, it's quite
likely that writing useful task-oriented help for that screen will be a
nightmare. There are ways around this (mainly by duplicating the code for
the screen so each situation has a unique resource ID), but unless the
extra time to do this is built into the programmers' schedule, it probably
won't be done, and you'll be left holding the bag.
This is related to item 2. Keep an eye out for problems like this in the
design. But it's better to address the possibilities before the design
stage -- before they become problems.
4) Get a *clear* understanding (and agreement) from the software developers
of how the help is going to be tested. Who's responsible for testing what?
Many projects I've been on test that the help comes up from the product
when requested; some test that it's the right help; some test internal
links. Few test that the help is actually helpful -- is that the editor's
job? Is there an experienced help editor available? Does someone test or
review the usability of the help ToC and keyword index?
5) What's the process for getting info to you when the design changes?
What's the review process? Do you know when you are expected to have help
ready to test? And a lot of other process questions. If the process isn't
clear, or you think it could be improved, now's the time to negotiate.
6) Does Doc-to-Help have a good way of tracking the status of individual
help topics? By that I mean, can you easily prepare a report showing what's
been written, what's been reviewed, what's been approved, etc. If not,
investigate how you're going to do this (an Excel spreadsheet, perhaps?)
with the least pain and wasted time. This is *THE* biggest issue I know of
for many online-help writers.
7) You didn't say how familiar you are with structuring online help, how
much experience you've had, etc. I would read, for example, Hackos and
Stevens' _Standards for Online Communication_. And there's a lot of other
useful info out there.
If some of the above isn't your responsibility (you didn't say whether you
are in a writing department or one of a team writing for the new product,
or on your own), nag the responsible person. If most of it's covered
already in your company's processes, you are indeed a lucky person.