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.
Tom Herme said:
>First, in regards to general organization and files, I have set up nine help
project
>documents, one top-level and eight for the main program areas. Is this a good
plan
>in comparison to some advice I've read and heard that a person establish
files for
>context-sensitive help topics, glossary topics, how-to topics, and overview
topics?
Tom, we organize the Help for our products by module and submodule. We
have nine Help systems, one for each major area in our software (for
example, set up, using, grading, class scheduling, etc.). Within each
Help system, topics are grouped by submodule in individual project
documents. I like this organization because when a submodule changes, I
usually only need to make changes to one of the files. Each project
document contains context-sensitive help topics, how-to topics, and
overview topics, as well as popups. If we organized by topic type, I'd
have to check every file for appropriate changes.
He also said:
>Second, I'm concerned about ensuring that context-sensitive topics can be
linked
>by the programmers to their software project. I define my own topic IDs using
a
>naming convention that follows file structures. I view the .hh files for ID
names and
>map numbers. So I know that I can supply map numbers to the programmers. I am
>confused by the use of IDH identifiers for context-sensitive topics. Do IDHs
need to
>be attached to every context-sensitive topic ID? Is knowing the map number
>sufficient for this?
We link our Help topics using context IDs. I supply the correct IDs
using an Access database. The data for the database is generated
automatically by our product to ensure all screens (data input and
report) are included; I then modify the context IDs to match the ones in
our .hh files and save the database. It's been tedious as we're
currently using Doc-To-Help and it changes the assigned IDs every time
you convert and compile the Help (that is, if you've made changes to a
doc file like adding or removing topics). I plan to convert the project
to RoboHelp (RH) as soon as this release is out the door. It's been my
past experience with RH that it doesn't change IDs on you. So I'll only
need to add IDs for new topics to the database (and remove those for
deleted topics), rather than figuring all of them out each time we
modify the Help.
Hope this helps!
*************
Kim Cramer
kcramer -at- ncslink -dot- com
Sr. Information Developer
NCS Education, Mesa AZ
*************
TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
