February 10, 2016

The 5 Principles of Single-Sourcing

image shows 5 round objects symbolizing single sourcing

What is Single Sourcing?

Single sourcing and reuse in technical documentation is getting more and more widespread these days. And for a good reason. It can make working with complex documentation much more efficient.

But mastering it may be quite difficult. It’s also a broad and complex area that is difficult to do justice, but that is not the point of this article. It is rather to share some of the thoughts and ideas I have used myself in my work with single sourcing, and in training others.

First things first, what is single sourcing to begin with? It is sometimes also
described as: “write once, publish everywhere”. But there are tons of interpretations of this. In the world of technical documentation, if we simplify it heavily, it usually means roughly that you want to write your content in one place (one “single source”), and then be able to achieve two main goals:

  1. Publish your content to several different output formats – PDF, HTML, Mobile, etc.
  2. Use the content you’ve authored in multiple contexts – e.g. reuse a piece of text (often called “topics”) as building blocks to produce do
    cumentation for several products or other variants, instead of having to copy and paste.

Of course the end goal is more efficient production and management of content. And to accomplish it, there are several technologies to help, such as e.g. XML-based standards and Component Content Management Systems.

These technologies offer a lot of different possibilities for single-sourcing, like filtering/profiling, variables, content references, and topic-based authoring.

However, due to all these possibilities it is also easy to initially get lost in all these techniques. And often to do it wrong, or even to overdo it.

The legacy of object-oriented programming

Don’t be intimidated by this heading if you know nothing about programming. Most technical writers are not programmers, and often don’t need to know anything about programming. You won’t need to for this article either, I promise.

So, you might ask, what does it have to do with anything?

Well, programmers have been struggling with the exact same problems as technical writers, and before single-sourcing ever became a popular concept in technical writing.

Programmers need to reuse code, and they need to make sure that their code is well-structured so that it is easily maintainable over time. Very much like the need for technical writers to reuse content and create a good structure. The difference is, programmers have identified the difficulty of working with this a long time ago, and have developed very clear and established principles for it.

I have found over a number of years of teaching the concepts of single-sourcing that it is often perceived as very abstract and a lot to take in initially. So I started applying a sort of similar technique for describing “principles of single-sourcing” similarly to how it has been done in programming. This article aims to describe these principles.

Now, there is nothing scientific about this, and the concepts have been around for a long time. There is also of course no “magic number 5”.

There may be other principles that could apply equally well. In some ways I am surely also over-simplifying. But I have found that applying these particular principles can really help in explaining the basic concepts of single-sourcing and reuse to technical writers, just like programmers have been helped by the principles of object-oriented programming, and this is what I hope to convey.

So here we go…

The Dry Principle

DRY stands for “Don’t Repeat Yourself”. And this is arguably the most basic and at the same time most important principle of all.

The very idea of single-sourcing is that you should start thinking that each time you “repeat yourself”, you may be doing something wrong.

So what you want to do is, instead of repeating the same piece of content in multiple places, you need to think: is there any way I can reuse this content instead?

As soon as you understand the basic concept of single-sourcing, this may sound like a given!

But…the fact is, it takes some time to get used to the idea of always looking for ways to reuse content. And the benefit of the principle is not really to add something new and complicated, but quite the opposite, it helps you keep this very foundation of single-sourcing in mind at all times by the very fact that it is so directly and simply phrased.

So if at any moment you find yourself thinking, “I’ve written something like this before”, this should trigger the principle Don’t Repeat Yourself – and then rack your brain to find a way to reuse, instead of rewriting it!

The KISS principle

The KISS principle stands for “Keep It Simple, Stupid”, or in the slightly more polished interpretation, “Keep It Simple and Straightforward”.

In programming, this refers to the fact that there are always a lot of ways to accomplish functionality, but the simplest way is usually the best. (With a bit of a stretch, you might think of Occam’s Razor as a similar principle.)

The same goes for single-sourcing and topic-based authoring, you as a technical writer will also have a lot of tools at your disposal, just like a programmer. And the idea of this principle is to make sure you use those tools wisely.

Just because you can, doesn’t mean you should.

It is a good idea to think of this principle as one that acts as a counter-balance to the DRY principle – i.e. do try to find clever ways of reusing content, but don’t overdo it to the point where your content becomes too complex!

So if you find yourself having a number of options to structure your content, achieving reuse, and one of them is really complex – achieving perfect reuse – and the other is simpler, achieving some reuse, but not 100%, well the choice might well be the latter. In choosing what strategy to use for creating your content, if the gains aren’t worth it, choose the simpler solution!

Because what you have to think about is, no matter how ingenious your solution of reuse is, you have to make sure that others can understand what you did, and also maintain it later.

When you get the previous principle (DRY), you will soon get into the mindset of hunting for reuse. This is good. But the KISS principle will then be helpful to balance this. Even to “kill your darlings” so to speak, and help you consider cases where reuse just isn’t worth it. You may see the possibilities for it, but if the technique required to achieve it makes the documentation hard to maintain, it may be better to let that particular reuse opportunity go altogether.

The Principle of Least Knowledge, or Only Talk to Your Friends

To refer back to the analogy of programming again, this has to do with the fact that if you create a lot of dependencies between programming functions, these functions won’t be reusable.

The same thing goes for topic-based authoring and reuse in technical writing:

You should aim to make your topics “stand alone”, and for instance be careful about creating “dependencies” between your chunks of content. To be more concrete, an example of this might be not to create links between topics unnecessarily.

As soon as you create a link between topics (a cross-reference for instance), you have potentially created a dependency. This means, that if you want to use that topic in any publication, you need to make sure that the topic it’s linking to is also included! And when you consider that you should aim to make topics reusable in many different contexts (for example documentation for multiple products), then you cannot take for granted that a target topic that you link to in one publication context will actually be present in another one.

The alternative name for this principle is perhaps more helpful. “Only Talk to Your Friends” – i.e. in this context, only link to or connect to other topics, if you know they are a close “friend”.

What would a “friend” mean in a set of topics for technical documentation? Well, if you know that one topic and another would always need to go together, then it may be fine to link to it or create a dependency of some sort.

Of course, if you have a good Component Content Management System, it will help you with a lot of these things. But overall, it’s nonetheless better to be restrictive about creating dependencies.

The Single Responsibility Principle

This principle refers to the idea that one topic (or function in the original programming context) should only have one responsibility, or “job”. This means, it should only fulfil one purpose/contain one piece of subject matter. For instance, if I write a topic that both describes the safety information about an engine, and also how to install it, I’m assigning two responsibilities to this topic. This should be avoided.

Because if I do this, what if the safety information about the engine could actually be shared with a number of other engines? If I mix the two information types, I’m making it hard to reuse.

The single responsibility principle helps us divide topics into smaller pieces, making sure that content is more reusable. By making sure we’re not trying to perform two functions at once (describing, instructing, etc.), we make it easier to reuse content.

The Abstraction and Generalization Principle

In the original programming version of this principle, it meant that if you have a chance to make a function generic instead of specific, do so.

In the context of technical writing, the same thing applies, but with a twist: if you have a chance to make a topic more “generic” with retained comprehension, do so. The whole idea behind topic-based authoring is that you should break down your content in smaller chunks of content, and then reuse them. So you need to make your topics as reusable as possible. If you make them too specific, they won’t be reusable.

For example, imagine you’re writing about two different (but similar) products. They have the same description, safety information and so on. And the only thing that differs is the product model name.

What this principle says in such a case is: if you don’t really need to mention the product model name, don’t do so! Why would you if it doesn’t add to the comprehensibility of the content? All you would accomplish is to make the topic non-reusable. Instead, if you leave out the product name, and the rest of the content is the same for both, you can reuse it!

Of course, there are situations where leaving out specifics might lower the quality of the documentation, and then you should not leave it out!

There are techniques to get around that and still adhere to this principle, such as using variables. But in the majority of cases where content is reusable, leaving out the specifics like product model names usually doesn’t make any difference at all to the reader. And then that’s the simplest solution (to hint back at the KISS principle).

To Conclude…

I hope this article has been useful to you. And remember that these are not scientific rules. I certainly didn’t invent them, I’m just trying to map them to the domain of technical writing and present them in a digestible format. They are not even by any means exhaustive. But if they help, that’s good enough. And no matter how you do it, there is no getting around the fact that you need to master the strategies of single-sourcing to get the benefits and the reuse you need to make your documentation more efficient.