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.
> I don't know if anyone who has never done it can appreciate the focus
> and concentration needed to do online help.
I fully concur. It's so easy to start one help item task and then get
interrupted, return to the project and find out an hour later you're
working on an entirely different item and never finished the task you
were doing when you were interrupted. Then, too, you can often get
sidetracked by a link you hadn't thought of before or some other
anomaly. You start prototyping and testing this new item, and find
yourself implementing it throughout the project, when in fact you should
not do that until a later draft.
It helps to stick to a discipline of procedures. Here are some ways
we've tried to keep production on track in a very complex product with
only two writers, an uncooperative and unavailable Development
department, and a brand-new Help design for a product release that
changes on the fly:
* Start with an outline and continually update it as you go along.
* Use a reference table for each series of screenshots, with associated
.bmp, .doc, topic titles, production notes, and a thumbnail of the
* During a procedure (such as adding How Do I topics), when an anomaly
comes along, put production comments (( I use double parentheses, and
sometimes highlighted as well) right in the body of the topic. Then
*finish* the current procedure on that file. Prototype/test the anomalies
in the next pass through that section of the help project.
* When a design/organizational/structural/process element is prototyped,
tested, and approved, it becomes a standard style. Document that
standard - even if it's only screenshot of what you are doing -- and add
it to a HelpNotes folder - which you use as the beginnings of a Style
manual and reference as needed throughout the production process.
Procedures that are set in stone also become checklists for the next
section of the help system.
* Keep a table of procedures - first column is the help filename, the
rest of the columns are each procedure. Check off the procedure when done
for each file (I use a date rather than just a checkmark). Add new
columns for new procedures when they become a standard.
There are always interruptions, from outside the help project and from
within the writing/production process itself. But using the discipline
of procedures and keeping a paper trail of your standards and procedures
gives you manageable production "chunks" as well as a relaunching pad
when you return to the project after an interruption.
I also find that documenting the standards (styles, organization,
procedures) as I go is the only time I really get to "imprint" these
things in my head -- since planning and production are going together and
there's not time to just plan and test. I make no assumptions that I'll
remember any detail, so I write down every one, pretending I'll be dead
tomorrow and someone else will have to pick up where I left off. I'd
hate to leave a mess for anybody. So far, that "anybody" keeps turning out
to be *me*.