Re: Technical writer dream

[Arnold Colodner <Arnold_Colodner -at- MAIL -dot- STIL -dot- SCITEX -dot- COM>]

     Sorry, I think you are talking about a nightmare, not a dream. Too
     many people think that you can repurpose material by just converting
     format. Tell, 'em, it ain't true!!

     Printed manual and on-line help are not one and the same. When on-line
     help is like a printed manual it is unwieldy and does not benefit from
     the power of the computer. Style is different, material is organized
     differently (hierarchy), supporting illustrations are different. And
     when you get to CD-ROM you have the power of animation, sound and
     other techniques to enhance the delivery and get more information
     across. The internet is another story, and combines some of the
     advantges of on-line documentation and CD_ROM. Of course, you can
     supply a full printed manual in PDF format, too.


______________________________ Reply Separator _________________________________
Subject: Technical writer dream
Author:  Alessandro Bottoni <albo -at- CADLAB -dot- IT> at INTERNET
Date:    7/16/97 12:02 AM


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