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: Single-Sourcing Online and Hard Copy From:Chet Ensign <Chet_Ensign%LDS -at- NOTES -dot- WORLDCOM -dot- COM> Date:Thu, 31 Aug 1995 09:43:22 EDT
John Russell
>> Ok Ok, Old question.
But always worthy of discussion.
>> Has anyone out there successfully single-sourced documentation for Windows
>> online help *and* a hard copy user's guide? ... If you have single-sourced
Windows
>> online help and hard copy manual (with or without success), please respond
to me
>> and give me your success (or horror) story.
John,
I posted an article about this yesterday, describing how we did doc and help
from a single source for a Novell product. I was also involved in a similar
project at my last job.
Our approach relied on SGML markup. We were documenting a Windows-based
database program. In that project, the writers who were producing the manual
would identify sections to be used in the help system using <help> tags.
(Actually, I don't recall the exact syntax, but this is still basically how it
worked.)
If the writer was documenting a section on how to save a report request, for
example, s/he would already be including text that described the components of
the report dialog box. The sections that would also be used in the help system
would be tagged with <help id="contxt string"> .... </help> where the contxt
string was the id value provided by the developers. Within that help element,
the writer could also mark portions of text with <nohelp>...</nohelp> which
basically said "don't pull this part for the help system." So, for example, a
paragraph that served some transitional purpose in the doc but would sound
awkward sitting in the middle of the stand-alone help topic could be left out.
To generate the help system, we simply ran a home-grown AWK program against the
documentation files. It would copy out and concatenate the <help> sections of
the document, convert our SGML markup to the necessary RTF tags, build the RTF
strings needed for hypertext links and subtopic lists, write the project file
and then feed the whole thing to the HCP compiler. Basically, we'd let the
computer build a new help system every night when we went home at the end of
the day. The developers had a directory set up on their file server for the
help system so we'd build it right down the back bone to there. They could test
out the help system anytime they wanted. It was a very smooth operation.
The writers reported that the very act of putting help tags around blocks of
text helped them think about how the explanation work standing all alone. They
were sensitive to the nuances of fitting text into the document in such a way
that it fit with the flow of the paper manual, but could also work when
presented alone in the context-sensitive help system.
We also generated the online version of the doc using the same program. And we
organized that material differently so that really, the end user had three
different sources of information.
The system took us time to build and get right, but it was an extremely
effective system once it was running.
Best regards,
/chet
Chet Ensign
Logical Design Solutions
571 Central Avenue http://www.lds.com
Murray Hill, NJ 07974 censign -at- lds -dot- com [email]
908-771-9221 [Phone] 908-771-0430 [FAX]
