Basics of Single-Sourcing

by Bradley Nice, Content Manager at ClickHelp — all-in-one help authoring tool

We are lucky to live in a modern society with all its know-how and inventions. The same is true for technical writers and the way they manage the content.

After changing from a typewriter to a computer, copy-paste became easy and quick. Why rewrite a document several times when there is a copy button. It has become a time-saver.

There are cases when a writer needs to make a lot of changes to the existing content or very few changes after the content is copied and pasted to a new location. This case is for a more advanced methodology called single-sourcing.

Every tech comm professional knows a single-sourcing notion. It 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 and using it in multiple documents and/or in multiple places in the same document.

Briefly speaking, it is when one version of the content exists in one location and is used repeatedly.

Single sourcing in technical documentation is getting more widespread these days. It can make working with complex documentation much more efficient. But to apply it wisely, you need to understand the specifics.

How to Use Single-Sourcing for Technical Documentation

• The core of this approach is in creating a “foundation” for the documentation, which will be easily and quickly completed and revised depending on specific users, their needs, and the characteristics of your current tasks. Single-sourcing makes the work of technical writers simpler and allows you to edit manuals immediately after any updates of your products are released. So instead of rewriting key information every time, you can simply reuse it.
• Try to avoid any links to other topics. The base text should be independent without any extra information. Otherwise, you will have to include the additional piece that the main material refers to when writing another document.
• Simplicity is very important for understanding any product and the principles of its work. So, simplify information when using a single-sourcing approach as much as possible. When doing so, the content can be applied to several manuals at once. It should be well-structured for the convenience of reusing it in the future.
• Describe one particular topic. This is the same as with the elimination of links — it significantly increases the reusability of your content. When the need arises in describing two or more subjects at once, you should divide the text into two or more semantic blocks so that they can be used separately.
• Go for generalization. Try to avoid specific names and metrics without changing the understanding of how a particular product works.

Single-Sourcing Features

1. Variables. A variable is a non-formatted piece of content that can be edited in one place but used in many places throughout your project. They’re especially good for a text that might change frequently, such as version numbers and dates.
2. Snippet. A snippet is a piece of formatted content that is heavily used in single-sourcing. Snippets can include text, tables, images, and whatever else can be included in a topic.
3. Conditional TOC. You can customize the way your topics and folders appear in the Table of Contents. Include or exclude any topics unconditionally, or only with specific output tags. For example, you may omit some of the topics from printed manuals and include extra for the online version.
4. Role-based access. If you make your documentation password-protected, you can assign different permissions to different readers of your portal. When they log in, they will have access only to the guides you allowed for their profile or role.
5. Conditional content. A condition is a feature applied to files or to different areas of your content so that some information displays in one output file format but not in another, or it displays only when viewed on a certain device or screen size.
6. Output styles. When you need to make your documentation custom-branded for different clients or partners, conditional styles come into play. Within a single project, you can vary fonts, colors, backgrounds, logos, and much more. This way every client gets uniquely styled documentation.

The single-sourcing approach has proved to be really effective in simplifying many tasks. By creating one document, you make a base for many others at once, you save the time for your specialists, reduce costs for publishing, use multiple output formats, and much more to it. So, don’t be afraid of complex rules that are important to adhere to when creating a single source. The efforts are paid off exponentially. Write once, use many times.

Have a nice day!

Bradley Nice, Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors