Single Source Documentation

Share on:

Who hasn’t experienced the frustration of tracking down the latest document (version2.0) with the most up-to-date information, only to discover on another drive, or attached to an earlier email, or even lurking on a parallel chat-channel, a document.v2.01 which is almost identical, but not quite?

Single sourcing content is the solution to the multiple variant document dilemma.

The clear aim of single sourcing is to create and maintain a single information source from which content for multiple distributions channels can be generated in whatever format and structure is appropriate for that channel.

From one document, for instance, you could create on-line web-based help, a printable PDF document and an Eclipse Infocenter. This has obvious advantages in that you have to maintain only one source document so that when the information changes you don’t have to synchronise those changes in all your published documents.

However, when you start to think of the way in which the final documents are produced (written) and consumed (read), maintaining one large document to do all this is not particularly efficient or effective.

On-line information is consumed differently to printed documents. For instance on-line help is usually accessed one screen at a time, with related screens of information a click away so the information is not navigated in a linear fashion but rather more randomly according to need. On the other hand, the organisation and structure of printed material is generally sequential: it may proceed, for example, from basic knowledge to advanced concepts.

A question of style

The presentation, or formatting of content is different depending on the output channel. Printed material will be constrained to page formats ( “Letter” or “A5” etc.); fonts that work well for paper documents are not always so good for screen reading. Moreover, low resolution images may be acceptable for web pages but are not production quality for printed output.

So while the information may be the same for on-line and printed material it is generally more effective to structure it differently as well as apply different formatting or presentation styles depending on the output.

Assembly line

If you are going to present your information differently in different channels, then why not also consider presenting different sets of information for different groups: beginners, management, support staff, developers.

Each group has different information requirements, although there are also sets of information common to them all. It makes sense to develop information in modules, joining them together, or assembling the modules, according to the needs of the different kinds of consumers.

Single-source approaches

Like modular programming, producing and maintaining modular information has it’s own particular challenges. It requires a change in the practices and processes with which content is produced, including:

  • Modular writing
  • Content Re-Use
  • Content assembly (with the potential for dynamic assembly)
  • Conditional processing

Why should I single source my documentation?

Save time - Content re-use saves time when your content producers are not re-developing existing information. New information is added as discreet modules leading to quicker, more efficient document production.

Save money - Less time = less money.

Improve Usability - Focusing on information modules that are usable in all formats will generally improve the quality of the content.

Improve Control - Document assembly allows you to create documents that precisely meet the information needs of consumers. The granularity of controlled access to information increase with modular content.

Improve Collaboration - Where a word processor allows only one editor at a time, modular documentation enables more contributors to work on information development.