RE: Single-sourcing Tool

["Bill Lawrence" <scribe -at- matrixplus -dot- com>]

Actually, I've been using such a single-source system for years.  Frame
can be part of the equation, but it isn't necessary.

The tools issues are the minor problem by the way.  Teaching technical
writers who grew up on WYSIWYG environments that it is more important to
tag-it-for-what-it-is can be daunting.  I worked at one company where it
worked very well, and another (with somewhat less technically-oriented
writers) where it was a constant struggle.  I currently work for a very
small company where I am the writing department, so that's no longer an
issue :-)

The first step is to translate your existing documentation into a
well-supported XML DTD/schema, such as DocBook or TEI.  I'm more
familiar with DocBook, so I'll stick to that.  You can store the source
in a conventional source control system (I'm now using CVS) or, if you
have the budget, you can get an XML aware content-management system.
There are many of these, and they can help a lot with work-flow issues.

DocBook is very well supported by the open-source community, and as such
there are powerful, free, XSL transformation scripts available to
transform you single source into all of the formats you've mentioned.
DocBook is rich enough to accommodate all of this, ranging from FAQ's to
CHM files and PDF files.  The DocBook scripts are called the Modular
DocBook Stylesheets, and are available on www.sourceforge.net.

If you're using Frame as your editor, that presents an alternative path
to print and PDF. There are other editors available, and they range in
price from roughly the cost of Frame to free.  The less expensive
editors require more technical knowledge to operate. There are also
other formatters (such as XEP) that provide an XML printing solution
using formatting object technology.  I prefer that route because it's
simply more flexible.

Turning your single-source into FAQ's, manuals tailored for specific
audiences or products, knowledge-bases, etc. is pretty easy as well.
The XSL stylesheets support "profiling" by checking for specific
attributes set within the tags.  They also support processing starting
at any point in the single-source document hierarchy.  

So, now you have a way to store your single-source and transform it into
any of the media that you mentioned.  Automating work-flow is still
somewhat of an issue, because there aren't an abundance of good,
inexpensive solutions for sending review copies around, collecting
comments, and providing digital "sign-offs."  Word is especially good at
that, but getting XML into present versions of Word, and then getting it
back to XML with the same structure, is almost impossible.  Since Word
is headed down the XML road, this may take care of itself soon.  

Acrobat would be helpful in automating work-flow if the commenting and
digital signature features could be enabled in the free reader.
However, they can't.  I'm currently experimenting with turning the
DocBook source into Microsoft eBooks for review purposes.  eBooks are
essentially XHTML, and do support commenting.  Also, they are as
portable as PDF files.  Other potential solutions might include
transforming the XML into HTML, and loading it into a WIKI.  

Regards,

Bill Lawrence
Senior Technical Writer
Matrix Systems

> 
> I posted on the Single-Sourcing SIG newgroup with regards to a "Grand
> Solution". This solution would encompass:
> 
> A) source for paper manuals and CHM help files
> B) source for website FAQs
> C) source for web queries through the website
> D) source for web queries "inside the firewall"
> 
> Its evident to me that an object-oriented database solution exporting
> XML is necessary to facilitate all four. The burning question: how?
> 
> I have read numerous white papers and books on Architecture of
structure
> and how XML output sucked into Frame and compiled as CHM will work.
What
> about actual, tangible, working systems? Does anyone DO this now? How?
> What are the tools? Workflow? Cost?
> 
> 
> Len Kirby
> Manager of Technical Communications
> Power Measurement Ltd
> www.pwrm.com
> 


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
Buy or upgrade to RoboHelp X3 today and receive the WebHelp
Merge Module for FREE ($299 value). RoboHelp X3's all-new
features include conditional text, completely re-engineered
printed documentation output, Context-sensitive Help Toolkit,
single-source layouts, and more!
Order online today at http://www.ehelp.com/techwr-l


---
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.