Single sourcing and its applicability to small projects
Single sourcing is used extensively and successfully for large documentation projects that involve thousands of pages or help topics. Is it useful for most small documentation projects? This article examines some of the issues.
What is single source documentation?
With single source documentation, the component elements of all the documents are written in one single source file. These elements might be single sentences, paragraphs or entire sections. The writers of the source file define which elements are required for each of the various documents. Some examples:
- A graphic image might be used in a document that will be printed, but it might not appear in online help.
- A customised version of software might contain a paragraph that does not appear in the documentation for the generic version.
- A set of manuals or online help files all contain items of text or graphics that are identical.
Single sourcing is more than just re-presenting a document in a different medium. For example, a printed version of online help does not mean that the online help is a single source document (despite what the vendors of various tools tell us).
Claimed advantages and counter arguments
This table lists some of the advantages that are claimed for single source documentation. Against each claim, there is a counter-claim that applies to small projects.
| Claimed advantage | Counter claim | |
|---|---|---|
| 1. | Eliminates redundant or repetitive information. Write it once, not several times. | True in the case of, for example, a set of documentation for related products, many of which share the same features. For a single product, there is likely to be little repetition. |
| 2. | Improves consistency across a set of documentation. | True if there is more than one writer, or as a result of eliminating repeated information. |
| 3. | Reduces errors when information is updated. Instead of updating several separate documents, writers update only the single source file from which the documents are generated. | Only true in cases where there is a single source for multiple documents. See counter-claim 1. |
| 4. | Frees writers to focus on content instead of format. | Disagree. For example, paper and online media have different properties. With online documentation, you can do wonderful things with hotspots on an image. You can't do that with paper. However, you could use callouts with textual cross-references. Therefore, in a single source document, you would need two versions; one for the online document and one for the paper document. Instead of having two versions in two source documents, you would have two versions in one source document, which you would then compile into two output documents. |
| 5. | Reduces the review time. Instead of reviewing several separate documents, review only the single source document. | Disagree. The review should be conducted 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. | Maybe. Not clear how this would be achieved for a small project. |
| 7. | Decreases cost of translation and localisation. | True from the perspective of advantage 1, which is not significant for 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.
Single Source Explanation, Simply Written Inc (www.simplywritten.com).
Various conference summaries, Single Source Summit, October 25, 1999, San Mateo, California.
RSS feed