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.

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