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.
This is the last part of my checklist series. Thank you for your private
responses. I have revised the checklist according to your additions, specially
some more pointers to other information.
To repeat it: This checklist is intended to define how, you as a writer of
online documentation, will interact with the programmers of your project. This
checklist will be my presentation at Forum 95, an international conference for
technical communicators on 14.-15. November 95 in Dortmund, Germany.
Prototypes
----------
J) Define prototypes for practically everything you are going to
write. Offer them to the programmers, as they should use them for
the user interface too. Write a style guide for all writers in the
project. This is the only way to ensure that different parts of
the program will receive uniform help.
Help Interface
--------------
K) Discuss the complete technical interface between the technical
writers and the programmers. The most important part might be a
"header file" that contains a symbolic name for any help topic
used in a context-sensitive way. Define a standard description for
every such symbolic name or you will be lost in hundreds of
unspeakable names like HLP_MAIN_PUL_FILE_OPEN.
L) Define who will write the header files. Often, the programmers
will insist on writing header files themselves and that excludes
many hypertext authoring environments you might want to use.
M) Tell the programmers you will write another header file for
purposes internal to the help system. You need additional symbolic
names for your glossary and other topics that cannot be called
from the program. Your (OS/2 or Windows) help compiler needs
symbols for these topics. You will defenitely add topics to your
help system at the end of the design cycle, when the programmers
are forbidden to do anything but removing bugs: This is the first
time you really see any really finished window.
Any Suggestions or additions?
If you wish to receive the check list, send an empty message to
onlchecklist -at- twh -dot- msn -dot- sub -dot- org
If you wish to join the Forum 95 mailing list, sent a message to
listserv -at- twh -dot- msn -dot- sub -dot- org -dot- the message should contain one or more of the
following lines:
