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.
Sounds like you want to use SGML (Standard General Markup Language)
with an online viewer such as provided by the DynaText system.
DynaText also supports Web-based tools. It is an expensive but elegant
solution. ArborText is the most common editor. Sorry, I don't have
addresses for these sites--a search engine should lead you to the
appropriate sites.
The idea behind SGML is that the information is an asset, which is
used in multiple ways. SGML tools allow you to "type" information,
define which types appear in an instance (such as a printed guide) and
how it will look in that instance, and extract information for an
instance--online help, printed guide, etc.
SGML is the grandparent of HTML, literally. A few SGML tags were used
to create the original HTML.
You might want to subscribe to the WinHelp list, which actively
discusses HTMLHelp and similar online solutions. To subscribe, send
your request to LISTSERV -at- ADMIN -dot- HUMBERC -dot- ON -dot- CA
I have a dream: a rational way to manage our double-faced documentation =
(paper manuals and on-line help/documentation, both on CD-ROM and on the =
Net) without re-write most of it.=20
If there were all the software tools I need, I would use this approach:
1) I would write a single documentation set, written to be as modular =
and as complete as possible (the way the reference manuals are made, =
plus a few chapters that you would normally find in a user's manual or =
in a tutorial).
2) I would define the kind of information, chapther by chapther, using =
something like the Information types of MS HTML Help or the HTML =
meta-info.
3) I would extract the two (or more) kind of information
4) I would print the "paper type" information on paper and convert the =
"digital type" information to PDF or HTML + CSS1, to be used as on-line =
help and/or on-line documentation.
In this way, every change you will make to the documentation will =
propagate automatically to the related documents, both on paper and on =
CD/Web site. You will have a single "documentation database" (or =
"information source") easy to maintain.=20
To do this, I would need:
1) A single publishing tool that could be used to make documentation for =
both the "platforms", something like FrameMaker + Acrobat.
This software should be able to manage hyperlinks and software-generated =
TOC and indices.
2) A method to define the two (or more) information types, something =
like MS HTML Help information types.
3) A selection tool able to extract one kind of information and put it =
in a different file
4) A conversion tool able to save the page formatting during the =
conversion (something NOT like MS HTML driver for Windows).
What do you think about this paradigm? Is it a rational way to manage =
the problem? Could it be implemented with the existing software, maybe =
adding a few Perl programs? Could/should it be used as a guideline for =
the development of new publishing software?
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
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
