RE: Single Sourcing - Myth or Salvation?

[Ed Manley <EManley -at- Solutionsplus -dot- com>]

Responding to John's post below:

I believe Single-Sourcing and Modular Documentation (topic-based or
object-oriented parsing of content) to be the Salvation of Documentation
Practices for the Software Development Industry. Now - how to do it?

Here is my basic vision - the first cut at requirements, if you will, for a
document management system.

I want to:
adopt modular documentation so that each artifact exists only once. 
eliminate multiple versions / duplicate files floating free in the
environment.
version control all documentation.
write text or post an image one time, in one place.
publish all documentation on our intranet.
publish selected documentation on the internet.
publish multiple versions - we market our product in various forms based on
licensed features - I want each client to get a User Guide custom to their
licensed configuration.
ensure that any party is able to contribute text and artifacts without
making them spend time on format.
control read/write access privileges.
be able to start at the User Guide level of detail and drill down to the
Technical implementation level for any topic of interest.
use a common tool, preferably MS Word for text and Visio for drawings.

That's enough for now - it gets my basic needs stated.

Answers to John's questions in caps below.

Ed


Subject: Single Sourcing - Myth or Salvation?
From: jgarison -at- ide -dot- com
Date: Tue, 12 Mar 2002 14:58:03 -0500
X-Message-Number: 67

Dear Techwhirlers,

I don't think that we've discussed this issue in a while, and it's something
that I think we're all interested in, at least peripherally. Please respond
to the following questions and I'll try to get some sort of summary together
in a week or two once the flames have died down.

Single sourcing is defined for this discussion as using one set of files to
generate both online help and printed documentation. Feel free to expand
upon this definition if necessary, but make your clarifications or additions
clearly known.

1. Do you currently use single sourcing, are you thinking about it, or will
it happen over your dead body? 

I AM AGGRESSIVELY PURSUING IT!

2. If you use it, how successful is it? Do the online results represent
good-quality online help? Do the printed documents represent good-quality
printed manuals?

DUNNO YET

3. If you use it, how much overhead is there? (I.e., does it take just as
long, longer, or less time than it would to do both separately?) How do you
know?

IN THEORY, IT WILL TAKE LESS TIME. CONTRIBUTORS OF CONTENT CAN DO JUST THAT
- AND NOT SPEND TIME WRITING/FORMATTING DOCUMENTS

4. Is it worth doing?

IS PURSUING THE SAME FAILED DOCUMENTATION STRATEGIES OF THE LAST TWENTY
YEARS IN SOFTWARE DOCUMENTATION WORTH DOING?

5. Briefly describe the process and techniques you use to create single
source materials.

DUNNO YET

6. Did you invent your own solution, inherit the solution, or learn from
someone else (Hackos, etc.)?

LOOKING UNDER EVERY STONE AT THIS TIME

7. How big is your company? [Small = < 100 people   Medium = <500 people
Large = < 1000 people  XLarge = > 1001 people]

75 PEOPLE - 3 TW'S


Thanks ... and this one should be fun!

AND EDUCATIONAL!

John


John Garison
Documentation Manager
IDe
150 Baker Avenue Extension
Concord, MA 01742

Voice: 978-402-2907
Fax:    978-318-9376
http://www.ide.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check it out! Get some cool freebies when you buy RoboHelp! You'll receive
SnagIt screen capture software and a 10% discount voucher for RoboHelp
Consulting. This special offers expires March 29, 2002.
www.ehelp.com/techwr
---
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.