Single-sourcing and small projects
Single-sourcing is used satisfactorily for large documentation projects that have thousands of pages or help topics. But, single-sourcing is not useful for most small documentation projects.
What is single-sourcing?
With single-sourcing, the parts of each document are written in one source file. The parts can be sentences, paragraphs, or sections. The writers of the source file specify which parts are necessary for each of the different documents. Examples:
- A graphic is used in a document that will be printed, but the graphic does not appear in online help.
- Documentation for a customized version of software contains a paragraph that does not appear in the documentation for the basic version.
- Each document in a set of reference manuals contains sections with the same content.
Claimed advantages and counter-claims
The following table shows some of the advantages that are claimed for single-sourcing. For small projects, we show why each claim is frequently not true.
| Claimed advantage | Counter-claim | |
|---|---|---|
| 1. | Removes unnecessary or repetitive information. Write information one time, not many times. | True in the case of a set of documentation for related products, many of which have the same features. For a single product, there is probably not much repetition. |
| 2. | Increases consistency for a set of documentation. | True if there is more than one technical writer, or because of removing repeated information. |
| 3. | Decreases errors when information is updated. Instead of updating many separate documents, technical writers update only the source file from which the documents are created. | True in cases where there is one source for many documents. See counter-claim 1. |
| 4. | Lets technical writers focus on content instead of format. | Disagree. For example, paper and online media have different properties. With online documentation, you use hot spots on a graphic. You cannot use hot spots with paper. However, you can use callouts with cross-references. Therefore, with single-sourcing, you need two versions (one version for the online document and one for the printed document). Instead of having two versions in two source documents, you have two versions in one source document, which you then compile into two output documents. |
| 5. | Decreases the review time. Instead of reviewing many separate documents, review only the single-source document. | Disagree. Ideally, the review is done in context, that is, from a user's perspective. Reviewing a source document is not the same as reviewing a document that the user sees. |
| 6. | Increases cost-effectiveness in information development and decreases time to market. | Possibly. Not clear how this can be achieved for a small project. |
| 7. | Decreases cost of translation and localization. | True from the perspective of advantage 1. However, advantage 1 does not apply to small projects. |
Resources
Single Sourcing, Ann Rockley, The Rockley Group Inc (www.rockley.com), 445 Apple Creek Blvd., Suite 120, Markham, ON Canada L3R 9X7, in Forum 2000 PreSeedings, Technical Communicators — Leading the way, June 12-14 2000, London, England.
Various conference summaries, Single Source Summit, October 25, 1999, San Mateo, California.
RSS feed