Basics of Single-Sourcing

  • 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.

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.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Bradley Nice

Bradley Nice

Content Manager at https://medium.com/level-up-web 👈. I write about web design, web development and technical writing. Follow me on Twitter and Facebook