Re: Technical writer dream

Subject: Re: Technical writer dream
From: Arnold Colodner <Arnold_Colodner -at- MAIL -dot- STIL -dot- SCITEX -dot- COM>
Date: Wed, 16 Jul 1997 14:01:27 EST

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


Previous by Author: Re: Friends at Work
Next by Author: Estimating pages per hour
Previous by Thread: Re: Technical writer dream
Next by Thread: Re: Technical writer dream


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


Sponsored Ads