Technical writer dream

Subject: Technical writer dream
From: Alessandro Bottoni <albo -at- CADLAB -dot- IT>
Date: Mon, 14 Jul 1997 15:22:21 +0200

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


Previous by Author: Re: Spacing after a period...
Next by Author: Technical writer dream made real?
Previous by Thread: Cancellation
Next by Thread: Re: Technical writer dream


What this post helpful? Share it with friends and colleagues:


Sponsored Ads