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.
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.
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.
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
