Templates are great!

Templates are great! If used wisely they support writers to concentrate on the content without bothering with layout or structure too much. If a template does not help the writer to deliver the valuable information efficiently, it should not be used. Otherwise your team ends up as a crowd of template zombies.

We are not saying that templates are necessarily a bad idea. In fact, they provide a very good way to transmit experience, particularly through checklists and a framework in which to ask questions. The problem occurs when the template becomes fixed in stone and the organization now assumes that every project is a carbon copy of the one that went before it.

Tom DeMarco. Adrenaline Junkies and Template Zombies: Understanding Patterns of Project Behavior

Pages generated by templates also support readers since they present a structure they expect. So this follows the Principle of Least Astonishment which helps users to digest information effectively.

Confluence provides templates in the form of blueprints.

With projectdoc we add some macros to support teams to define their templates more easily. There are a number of free additional add-ons based on projectdoc that provide a number of space and page blueprints. Furthermore these free add-ons are open source and available via Bitbucket. Software developers may fork them and adjust them according to their requirements!

In this article we give a brief introduction to blueprints and in two follow-ups we'll give some tips on how to use them to boost your productivity.

Features of Blueprints

These are the features of blueprints that help to create content collaboratively:

Template authors define the basic structure for pages of a given type, such as howto articles. This helps teams to create content that is similar in structure and layout. This makes it easier for readers to find and digest information.

Confluence know blueprints in two flavours:

1. space blueprints to create spaces
2. and page blueprints to create pages.

The Create Page or the Create Space Action open a dialog that shows all available templates. This makes it easy for authors to find out quickly which tools are available to create new content. By selecting a template the user starts a process to create a space or page of a given type.

The wizard guides the author through the creation process with explanatory texts and by asking for additional information that influence the content of the new page.

There are also some limitations to the concept of blueprints:

For Confluence the created space or page is typically the end of the story. The generated wiki content is detached from the template. Any changes applied to the template do not affect the already generated space or page instances. If you need to apply a change to all existing pages you need to employ some scripting.

Blueprints are designed to get wiki users started quickly. Therefore they create content that shows how to use some of the features of Confluence. This may be great for new users, but is usually annoying for all others. The content that is not needed has to be removed manually. To workaround this problem you may create your own blueprints that reflect exactly what you and your teams need.

Let's delve into this last point deeper in the next articles and show some tools and techniques to help you to define your blueprints.

In the next article we will look into some macros to define page blueprints. The last article will have some tips on creating space blueprints.

Conclusion

Here are the take-away points of this article:

1. Employ templates to support
   
   1. writers (concentrate on content not structure or layout)
   2. readers (familiarity with structure and layout for types of documents)
2. Problematic may be
   
   1. updates to the template since the already created pages get not updated
   2. instructional text in the create page since it has to be removed manually

In the next article we delve into helping authors create content without distracting readers with cluttered documents.