Use Templates

Define a basic structure for all artifacts of a given type. Readers will have an easier job on finding and learning about the information in your documentation.

Domain
Documentation
Type
Knowledge Organization, Collaboration
Principles
Principle of least Astonishment, KISS Principle, Teamwork

A team needs to create a documentation collaboratively. Readers of this documentation need to think that the documentation has been written by one person. This makes it easier to understand the information.

How can we reduce the work for knowledge workers to provide information for the documentation?

Structure

Use document templates to define a basic structure for all documents of a given type. Readers will have an easier job on finding and learning about the information in a document.

Use space templates to organize documents within you documentation. This will lead to a similar structure for all spaces a reader is visiting. Readers will have a much easier time to find information in spaces whose structure is familiar.

Advantages

  • Documents are similar in structure and therefore easier to digest by readers
  • Authors do not need to reinvent the wheel and can build upon lessons learned by the team or organization

Disadvantages

  • Beware of becoming a template zombie! Templates are tools to support authors with a proven structure that served the team well in the past. Authors need to be encouraged to focus on the information they want to deliver by adjusting the structure and even the formatting as they seem fit.
  • Templates need to be created and continuously adjusted to the changing requirements of the team.

Related Practices

The following practices are related to this practice.

Employ a Style Guide
All publishing organizations define a style guide for their published information. Such a guide supports teams to write in a similar tone, making it easier for readers to digest the information.
Maintain a Glossary
To enforce a common understanding of the domain, a glossary should define the terms important for the project. This also supports the ubiquitous language and makes sure nobody is left behind.
Focus on Content
Make it easy for knowledge workers to focus on content and remove the need to define the document structure and formatting on a ad-hoc basis.

Resources

For more information regarding this practice please refer to:

Document Types and Templates
Document types (or doctypes for short) define a set of properties and sections. Each doctype matches at least one Confluence Page Blueprint. Confluence Page Blueprints are a collection of templates, but often the collection contains only one element.
Doctypes
Doctypes define properties and sections for documents. They are essentially Confluence Blueprints that help to create pages in your wiki based on templates.
Document Properties Marker Macro
A table containing document properties. Three columns: name, value and meta data (aka controls) to a property.
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.