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.
Chris Fitzgerald is writing <<... documents for our systems' software. The
software changes rapidly and a drastic new version is being written right
now with a release sometime in the early new year.>>
Probably the best thing you can do in such situations is start working with
the developers so you can get a handle on the development process; you'll
need to understand how they work before you can plan your attack on the
documentation. If there's any openness to the idea of freezing the interface
or functionality early in the development process, then tinkering with the
underlying code for the remainder of the development schedule, promote that
approach strongly. You'll probably never get a full interface freeze, but
you'll have a much easier time documenting (say) the "Save" function if that
function rests peacefully in the File menu rather than changing locations
daily. And if you can't get anything resembling an interface freeze,
concentrate on documenting the main logic of each function, which should
remain more or less constant, and plan to do a final pass so you can revise
the text to correspond with the interface once it finally does stabilize.
<<It's in need of a help system as a means to alert users of the ongoing
changes and multitude of functions, but I'm not sure where to begin.>>
Start with a clear understanding of what the users will need to know, and a
checklist of all the topics you'll have to document (e.g., every menu
command, every icon, every module of the software). Try to persuade the
development manager that you can't produce documentation that resembles
reality until everyone agrees on that reality (i.e., until he can stabilize
the software's interface); he should make a final decision soon about what
will appear in the current version, and then stick to it. Once that target
is stable, you can begin productively documenting things. Until then, try to
identify the parts they _have_ finished tinkering with and concentrate your
efforts on those parts; if you're lucky, they'll have finalized some of the
other parts by the time you're done, and you'll be able to start work on
those. If they're still tinkering, start documenting the logic itself (e.g.,
"this module lets you move the tip of the microscope. [details] I have no
idea how, but I'm sure we'll figure it out before we ship the software"; the
latter sentence is the one you'll revise once they figure it out).
<<I started writing for this company 3 months ago and have never written
online help.>>
See if you can't hook up with some local STC members (head over to
www.stc-va.org to find their list of chapters) to start discussing this. A
full course in help design might be better, but that may not be possible
given time and financial constraints, and there are bound to be local
experts who can help. In the absence of such support, spend some time with
help systems and pay close attention to your reactions: if you like
something, make sure it's part of your help system; if you dislike
something, don't do it (or figure out why you dislike it and come up with a
more usable solution).
<<I'd like to write the help system as the engineers write the new system.
(Can this be done?)>>
That's a tough task, since there are more of them than there are of you, and
if you have (say) five engineers changing the interface for 50 modules,
you'd have to check each module daily to update your documentation. Better
by far to figure out some way of learning when each part of the interface
becomes stable so you can document it.
<<We do have RoboHelp and I just installed it. We use FrameMaker on a Mac to
create the hardcopy documents, but I know that the way people read manuals
and online documentation is different. By the way,the software is written
for PCs.>>
You're obviously using RoboHelp on the PC, and that means you've got Word,
so you're going to have to figure out a way to get information efficiently
out of Frame/Mac and into Word/PC before you begin. Once you know how you're
going to do that, you can work on both platforms (Mac for print, PC for
online) with some degree of efficiency. As a registered Mac evangelist, I
hate to mention this, but it might make much more sense for you to migrate
to Frame/PC, since that way you remove one more obstacle (file transfer) and
the need to have two computers running simultaneously. On the other hand,
I'd love to have both computers running simultaneously, so if it makes sense
to stick with the Macs, by all means do so.
<<Where do I begin?>>
Since this is your first help system, keep it simple. Make a list of topics
before you begin, and spend some time figuring out how to link those topics
in a logical hierarchy. For example, consider creating a topic entitled
"Menus" (or one topic per menu if the menus are long) that lists all the
menu commands, then list each of the menu commands under that topic in the
order they appear in the menu (use subheadings to group the commands by
menu). Make each command name a link to the appropriate help topic. For
example, if there's a moderately simple and consistent series of steps that
all users must follow for certain tasks, include that sequence of steps as a
topic (entitled "how to..."), and link each step to more detailed
information on that step. Now create a topic entitled "What you can do with
MicroScopeMaster" that lists all these tasks, organized into logical
categories. And so on. Consider the problem this way: _You're_ approaching
the software for the first time, so ask yourself what types of information
_you_ would want to have available. Then create it. (Better still, talk to
the users of the software. But realistically, you may not have time to do
this.)
And don't forget to come here with "dumb" questions. You'll start asking
fewer of them after a while, as you start to get the hang of it.
"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
