The Basics - What is Single Sourcing?

A concept that comes up regularly when discussing best practise in technical writing is single sourcing.  What is single sourcing, and why is it often considered to be best practise?

Single sourcing can refer to any one of the following:

• Creating one document and producing it in different formats (e.g PDF, CHM, HTML, etc);
• Creating one document and using it as the basis for different documents (e.g. Installation Guide, Configuration Guide, Administration Guide);
• Creating a topic or piece of content (often called a "chunk") and using it in multiple documents and/or in multiple places in the same document.

Single sourcing is an example of the "Create once, use many" philosophy. It is also known as content reuse and is analogous in concept to code reuse, in that you can change the source code/documentation, compile your project and create a new deliverable with that change made everywhere the content is reused.

Markup languages like HTML and XML allow the divorce of content and presentation. The essence of single sourcing is to write the content once and then use markup to present it in different ways.  This can be in a different format - PDF, CHM, HTML, printed, etc - or in the same format but with different content "chunks". Large, homogeneous documents such as entire help files don't lend themselves to single sourcing, unless identical copies are going to be created in different formats (e.g. a PDF and a printed format).  Therefore single sourcing requires a topic based authoring approach, where individual topics can be reused in different outputs and in different formats.  It is for this purpose that DITA and its structured topic approach were designed.

 

What are the Benefits of Single Sourcing?

The primary benefits of single sourcing are that it:

• Has a single content source to maintain;
• Prevents out-of-synch problems;
• Reduces rewriting of the same information;
• Reduces review and editing load;
• Increases consistency of documentation.

Structured, reusable content also provides an element of future-proofing against new distribution channels such as mobile or social media.  A new presentation wrapper will be needed, but the content can still be reused.

An additional benefit is the concept of conditionality.  Conditionality means the ability to set conditions on when a particular topic or "chunk" will be added to an output.  This can be used to provide customised content to different customers or groups of customers, e.g. standard setup information for a particular sector, or bespoke documentation with a particular customer's or group of customers' configuration in mind.  Once the conditionality is set up in your help authoring tool, new versions can be created at the click of a button. 

Let's take an example.  You work for a company that sell the ACME Budget Software product.  ACME Budget Software is designed to help both SMEs (small-to-medium enterprises) and large companies manage their budgets.  50% of the ACME Budget Software product is intended for use by both SMEs and large companies, 20% just for SMEs, and 30% just for large companies.  Your documentation can therefore single source 50% of the content, and you can conditionally include the 20% (or exclude the 30%) for the SME documentation and include the 30% (or exclude the 20%) for the large company documentation. 

 

What's the Difference Between Single Sourcing and Multi-Channel Publishing?

If you've heard the term "multi-channel publishing" then you might be wondering what the difference, if any, is between that and single sourcing.  There's no concrete agreed answer in the technical communications industry, but this is my take on it (other opinions may vary). 

The single sourcing "output" is equivalent to "channel" in multi-channel publishing.  The difference between single sourcing and multi-channel publishing is that multi-channel publishing can use single sourcing but doesn't have to, whereas by definition single sourcing is designed for multi-channel publishing (and wouldn't have much point without it).  In single sourcing, the content, again by definition, is the same wherever it's published (use of variables not withstanding).  In multi-channel publishing the starting content is the same, but the final delivered content doesn't have to be.  This is particularly so in the case of different delivery mediums such as printed brochures, blog posts, web help, tweets, and so on.

 

What's the Difference Between Single Sourcing and Variables?

Single sourcing uses a block of text (including graphics if required), normally a few lines or more. Examples could range from a two line explanation of a field to a full topic on how to complete a procedure.  This block of text can be used multiple times within a single document and/or in multiple documents.  Variables are a few words, such as a company name, release number, website address, etc, which could change at some point in the future, or need to be different in different outputs.  Variables are embedded in your documentation, and when you change the text of the master variable, the text of the embedded variable changes everywhere in your documentation. If you have multiple outputs you can set the same variable to have different values for different outputs.  An example might be a different Support desk number for standard and Premium users of a product.

Note: I'm using "variable" as a generic term to describe a few words of text that can be placed as many times are you like within a document.  In a help authoring system like MadCap Flare there are both snippets (called text insets in FrameMaker) and variables, and there are important differences between them, but that difference is not relevant to this discussion.

 

When is Single Sourcing Used?

Single sourcing is useful when you have multiple people or teams working on different documentation for the same product.  For example, you might have:

• Technical Writers providing end user documentation;
• Trainers providing training documentation;
• Field Engineers providing implementation and configuration documentation;
• Support staff providing FAQs and knowledge base articles;
• Sales Engineering writers providing tender and demonstration documentation.

In these circumstances, having pre-written and approved chunks of text can save time and effort on the part of multiple people and teams.  This gives a good return on investment for single sourcing.  In other words, the greater the number of target audiences and the greater the number of distribution channels, the greater the advantage of using single sourcing.

But where a team of writers is working collaboratively on the same documentation deliverables, single sourcing is less useful unless you have tightly proscribed standards and structure for the deliverables. This is partly because writers tend to have their own styles, and unless proscribed otherwise what one writer provides will read differently to another writer.  The different styles are not necessarily better or worse, they are just different, but that is jarring for the reader and doesn't allow the reader to develop a consistent expectation of how the document will read.  The other reason tightly proscribed standards and structure are needed is because the content needed in one deliverable could easily be subtly (or grossly) different to the content needed in another document.  This might be solved easily by using conditions, but often the only way to solve the problem is to rewrite the content.  Tightly proscribed standards and structures will either prevent this, or they'll make it obvious before you start a project whether or not you've got existing content that can be reused.

 

Why is Single Sourcing Best Practise?

DITA is a very popular documentation paradigm, and is designed for single sourcing.  This popularity is why help authoring tools normally come with at least some DITA support baked right into the product.  For the proponents of single sourcing, the benefits as listed above make single sourcing an obvious best practise due to the efficiency and return on investment that it provides.  This is a very popular view.  

However, it is not the only view.  There is a view which considers single sourcing to be an inappropriate adaptation of the object-oriented code reuse philosophy, and that view generally holds to the idea that writing documentation is necessarily a different type of creation to coding.  As such, this view sees single sourcing as lacking feasibility in the real world, at least to the point of providing all of the benefits that proponents of single sourcing claim for it.  The most well-known articulation of this view can be found in The Myth of Single Sourcing by Michael Hiatt.  You don't have to choose a side - personally I think single sourcing works well in some situations and poorly in others - but it's always useful to understand the counterpoints no matter which view you favour.