Single Sourcing Documentation
Single Sourcing DocumentationIn a modern project, you need documentation in potentially several forms. You may need several among the following:
The challenge to the technical writer is that the same information must be created and maintained in several different formats. Technical writing professionals will often get very particular that the information is NOT the same in these different environments. I say that they haven't thought hard enough about the problem. You need the same information everywhere, just formatted differently, and presented differently.
If you can create a "database" of information such that the documentation in each format is generated from a single information source, then you have done a great deal to make sure your documentation is accurate, timely and created with the minimum of resources.
We started doing single source documentation back in 1996. At the time the tools were quite limited for this sort of thing. At the time, we settled on using Framemaker as the database source, and Quadralay as the engine to target each output format. It worked fairly well for all the reference material that had to be presented and maintained in each format. It did very little to help in the more narrative User Guide type documentation. Getting a handle on the reference type documentation saved us a ton of money and effort.
Now, will single source documentation work for the reference material for every project? Probably not. But if you have a project where the same reference material shows up in F1 help and printed manuals, this approach is very practical and saves a lot of headaches in the long run.
Like object oriented programming, single source documentation takes time up front that is returned ten fold down the road. It must be done correctly. Your documentation architecture becomes much more important than the design of a particular document. It's complicated, no doubt about it. But it can save a ton of effort down the road.
To learn more about Quadralay (I have no connection to them other than as a successful customer) see http://www.webworks.com If there are other companies doing single sourcing, please add them (ah the joys of Wiki).
When I was doing this project, Wiki wasn't available (or I hadn't heard of it). If I were designing my project from scratch now, I might use Wiki as the documentation source, and try and figure out a way to generate the other formats needed from the Wiki source. In other words, I think Wiki might serve as a better repository for the raw data used for multi target documentation generation than Framemaker did. It's an untried theory, but I think it could be very interesting to try.
Good luck with your extreme documentation project.
EditText of this page
(last edited November 18, 2005)
or FindPage with title or text search