Reduce redundancy by having one source of truth for each information. This way the written information is more easily reusable in other documents and - which is even more important - it is referenceable. Single sourcing demands automation.

Domain: Documentation
Type: Knowledge Maintenance
Principles: Single Responsibility Principle, DRY Principle, Separation of Concerns, Self Documentation Principle

Creating documentation collaboratively requires teams to reuse information in order to create documents quickly and just-in-time. Changes to the documentation have to be applied quickly and with no redundancy. Otherwise it is easy to end up with out-dated information.

How can we ensure up-to-date documents without spending much resources?

Structure

Single sourcing is a method for systematically re-using information. With this method, you develop modular content in one source document or database, then assemble the content into different document formats for different audiences and purposes.
Although its primary goal is to save time and money, single sourcing improves the quality of your documentation.
Kurt Ament. Single Sourcing - Building Modular Documentation. 2003

Single sourcing requires some form of automation. Information often needs to be aggregated, filtered or simply transferred from its source to a alternate representation or location.

Advantages

Documents that are dedicated to a encapsulated piece of information are less often subject to change.
Single sourcing reduces the cost of maintenance of the documents life-time.

Disadvantages

Writing modular documents for reuse is more difficult and needs training.
Content reuse may result in constant refactorings where text snippets are extracted from an existing document into a module for transclusion.

Related Practices

The following practices are related to this practice.

Provide multiple Views: Provide views on your topic-based documentation.
Dynamic Links: Build a navigation to related and associated information by the use of document properties and dynamic linking.
Single Point of Access: Users require a single point of access to all information relevant for a project.

Resources

For more information regarding this practice please refer to:

Transclusion Macro: Transcludes content from a document marked with the content marker macro.
Section Macro: Renders a section, if the body is not empty. Supports authors to create content, clutter-free rendering without empty sections. Allows to transclude the content.
Transclude Documents Macro: Renders transcluded content fetched from documents of a result set.
Module: A documentation module is a fragment which is usually transcluded by other documents. The lifetime of a module document is independent of the lifetimes of the documents that reference it.
Section: Sections of a document are typically part of a document. But the size of sections may vary. To support a team to write collaboratively on the documentation, a larger document may be subdivided into external section documents.
Information Systems Extension: Add-on to extend the projectdoc Toolbox to integrate remote information systems.

pattern

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Structure

Advantages

Disadvantages

Related Practices

Resources

About

Keep up-to-date!

Powered by