Slipping Back to Single Sourcing (WAS:On-line vs. print (WAS: Of myth and reality)?)

Subject: Slipping Back to Single Sourcing (WAS:On-line vs. print (WAS: Of myth and reality)?)
From: eric -dot- dunn -at- ca -dot- transport -dot- bombardier -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 1 Aug 2002 17:26:41 -0400




Ed, your post brings discussion back to principles of single sourcing. A
direction I'm trying not to have the other thread take. First I'd like to have
the list discuss the similarities and differences between the two sets of
requirements. Because all the vehement "they're so different, and can't be
reused" responses were so present not that long ago, I thought they would all
contribute to this thread to show the vast number of incompatible requirements
between on-line and print. Interestingly, all points brought up to date in this
thread IMO fall under the 'minor difference' or 'easily resolved' heading.

Personally I believe the differences add up mostly to only a few bricks, the
mortar, and the order in which they are assembled.

So far it would seem that both on-line and print should be:
- clear and concise
- be well indexed
- be well structured
- have a table of contents

The only real differences are the inclusion/exclusion of screen shots, where the
'page breaks' occur, and how the user manipulates/accesses the document.

IMO even many items (tutorials for example) identified as specific to one form
could be reused and made to benefit the user in other output formats as well.

Interestingly, I'd say that if you believe being 'lost in hyperspace' is a bad
thing and that HTML tocs alieviate this greatly, we've squashed the idea that
on-line documentation is non-linear. It would mean the best on-line
documentation is organised in a well structured, defined, linear manner. It's
only accessed in a non-linear manner.

<<If I keep each object as an artifact - a separate file, how am I going to
organize/manage them? I can see the beauty of building the on-line or printed
guide by calling the objects in some logical order...but we're talking hundreds
of discrete files to manage.>>

Well, it really all depends. Without good organisation and a keen understanding
of what your keeping as artifacts it can be a monumental task. Hundreds of files
can be an understatement. Our approach created tens of thousands of artifacts
when you count illustrations.

Without a tracking/management system, it is still possible to single source
using an organised approach using variable and conditional text. Which was the
point of the single-source defenders in the previous thread. As my experience is
with FrameMaker and FM+SGML, I think that the documentation for MIF2Go isn't
such a bad idea of where to start. Even if you don't have FrameMaker you could
download the docs at www.omsys.com and have a look. IMO they only show where you
could start and could be refined, but really I think that is what the list
should be discussing instead of sniping. How can the process be refined to
improve both on-line and print documentation.

To better visualize how to reuse text and information, I think you really have
to approach the subject first by identifying the essential information. Then you
identify the 'filler'. Often much of the filler is just the assembly and the
functional items and doesn't actually require any creative work.

It's much like building with bricks and mortar. The final structure can take
many valid forms. I think what offends many Techwriters is that the discussion
of single sourcing in this light squashes some internal longing for 'creative'
writing that they have deluded themselves into believing was being fulfilled at
their current day job. ;-) Sure some of the bricks can still be flowery and
decorative, but the vast majority of the content of any sound document is good
solid brick.

Eric L. Dunn




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Buy RoboHelp Deluxe starting at only $798: you'll get RoboDemo, the hot new
software demonstration tool that's taking the Help authoring world by storm,
together with RoboHelp Office. Learn more at http://www.ehelp.com/techwr-l

Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.


Follow-Ups:

Previous by Author: Re: On-line vs. print (WAS: Of myth and reality)?
Next by Author: Slipping Back to Single Sourcing Again (WAS:On-line vs. print)
Previous by Thread: Re: Include error messages?
Next by Thread: RE: Slipping Back to Single Sourcing (WAS:On-line vs. print (WAS: Of myth and reality)?)


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


Sponsored Ads