RE: Cross-product documentation strategy

["Tammy Lloyd" <tlloyd -at- xaware -dot- com>]

Hi, Walter,

I think the issue that your e-mail message is really skirting is how to single source the content produced by multiple writers for multiple products across all output types. 

Here at XAware, we've faced the same type of situation; however, with a few differences. 

There are only 2 writers on the documentation team here and we must maintain JavaHelp, PDFs, .txt files, and soon context-sensitive help for 2 different products. Although we are small, we maintain thousands of pages of documentation. 

To support all of the outputs we require, we maintain our content in FrameMaker and Veredus (by Rascal Software). Ultimately, we are working towards storing all of our content in Veredus from which we will build the JavaHelp, context-sensitive help, and PDFs as necessary.  

In FrameMaker, we use a combination of conditionalized text, text insets, and variables to maintain different versions of one book for 2 products. 

You are absolutely correct in that single sourcing will challenge all of your technical writers' writing skills, as well as, their grasp of FrameMaker's capabilities and that of any other product they must use. In some ways, the content will need to be brought up to a much higher level than it is already written. 

In order to single source between products, it's necessary to determine the information that can be used across all or some of your books. Next you must determine how that information can be broken down into pieces (I recommend no less than a paragraph) to conditionalize between products. 

Realize that when you use text insets in a book, then perform a search and replace or spell-check across the book that the text insets are ignored. For this reason, I recommend building a book in which only the single sourced content is referenced, this way one of your writers can easily do search and replaces and spell checks across the single sourced content. It saves a lot of time. 

All of our content is maintained on a network server, so that both writers have access to the content. We have a single sourced content directory in which we store the pieces of content that get used in multiple places across multiple books (e.g., introductions, generic steps for accessing a specific tool, screen shots, etc.). 

As far as information goes, it sounds like your writers will need to expand their understanding of the tools and how/when they are used together. This, I suspect, will give you the direction you need to take in order to single source the content. 

Also, for the .txt files, I've been maintaining our Readme and release notes content in a .fm file then using FrameMaker to save the file out as a .txt file. It works like a charm for us. Of course, you may already be doing this. 

I'm afraid my expertise in single sourcing is limited to FrameMaker and Veredus and I have no suggestions for your use of RoboHelp. 

If you have any questions, please feel free to ask. 

Good luck!

Tammy Lloyd
Technical Writer
XAware, Inc. 
2060 Briargate Pkwy Ste 150
Colorado Springs, CO 80922
719.884.5416

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl

WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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.