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: On-line help and manuals From:mpriestley -at- VNET -dot- IBM -dot- COM Date:Thu, 16 Feb 1995 14:02:13 EST
A number of people have asked for more information on the way I'm managing
this. To reiterate, I'm using a single source for both hardcopy and online
information. The various output formats are:
- hardcopy postscript
- hardcopy list3820 (an IBM format)
- online BookManager (a multi-platform online manual format)
- online INF file (OS/2 standard for online information)
- online HLP files (OS/2 standard for online help)
The source for the hardcopy and BookManager is nearly identical, and uses
BookMaster tagging.
The source for the INF and HLP format is a similar tag language, IPF;
I get the BookMaster source into IPF tag format using a conversion utility,
plus a number of macros that add INF-specific formatting information.
The INF file has much the same content as the hardcopy and BookManager versions
but with additional navigational aids (added hypertext links, orientation
cues, etc.), and some additional reference information (explanations of
messages etc.).
The HLP files contain a subset of the reference information that is suitable
for contextual help (eg, descriptions of compiler options).
The IPF format (for the HLP and INF files) is very similar to the BookMaster
source format, so conversion is (relatively) painless. BookMaster supports
conditional processing, which allows me to insert, delete, and reorder
sections based on conditions I set at processing time
(eg "when 'hlp' delete...").
When the differences in format between INF and hardcopy were predictable,
I tried to make the conversion part of a macro, rather than using conditional
processing which muddied the source file and made the source harder to read.
For example, I was adding orientation cues to the online (showing the reader
where they were in the document), and used a macro to insert this information
rather than manually inserting and maintaining it.
This still ended up being quite a lot of work. But our particular product
requires a lot of documentation, which is updated and released frequently. As
a result, keeping the information in synch and up to date is a priority.
This made it worth the extra effort to maintain the source in one set of
files, rather than having a different set for every medium.
I've probably been completely unintelligible above, since I'm neck-deep in it
at the moment and lack the time to step back and explain this properly. In
any case, the technical details of the processing and macros, and the
different output formats, are unlikely to be of interest to the whole list.
I hope I've at least given an indication of the kind of processing I'm doing.
It certainly isn't painless, but in my case the benefit is worth the cost.
Take care,
Michael Priestley
mpriestley -at- vnet -dot- ibm -dot- com
Disclaimer: speaking on my own behalf, not IBM's.
