Page and Space blueprints are a great tool to structure information in Confluence. They support teams to create pages and spaces with focusing on the content, less on the structure, not on the layout. With this tool new pages and whole spaces can be created with wizards in very little time.

One great thing about blueprints is that they can be managed as add-ons. Teams can have their blueprints designed and maintained as versioned Maven projects. These add-ons can be easily shared by team working on different Confluence instances. Unfortunately creating new blueprints takes quiet some time. And the work is often not very rewarding since a little misspelling can require some minutes in getting it right. Error messages are not the API's strong suite.

After about two year of writing a number of blueprints for the projectdoc Toolbox, we finally came to the conclusion that we need to have some tool support to write blueprints. We want to come to the point where writing blueprints and create new add-ons with blueprint sets is no longer a great deal.

Principles

In the past we have come up with some simple observations that we like when using blueprints

Have sets of blueprints that work together, using existing blueprints
Have at least one space that provides a basic structure for the domain of the blueprint set
Create navigation by dynamic linking
1. Provide a type blueprint for most of the blueprints
2. Show pages of a given type
3. Show child pages and a reference to the parent

After the creation of a new space, everything should be ready to work.

Types of Pages

When we create new doctype add-ons there are typically three kind of pages

Pages that contain information of a given type (e.g. a doctype to document systems)
Pages that categorize this type (e.g. system type documents)
Pages that categorize this and other types (e.g. documents that specify phases in a lifecycle)

A System, a System Type, and a Type

With this a team may document a system (e.g. a JIRA instance), associate it with a system type (e.g. issue management system), and set a lifecycle phase (e.g. In-service). On the issue management page there will automatically be listed all issue management systems and on the In-service lifecycle page, all systems (and maybe other entities with a lifecycle) that are actually servicing will be shown. Only one document is added, but two indexing pages will automatically reference it.

The Tool

We created a first beta version of a plugin for maven that should make it a lot easier to create these three kinds of pages. We do this by specifying descriptors for the blueprints we want to create. Here is the example of a doctype with it own type category.

Click here to expand the System Descriptor

System doctype (with a type)

<doctype
  xmlns="http://smartics.de/xsd/projectdoc/doctype/1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  id="it-system"
  base-template="standard"
  provide-type="standard-type"
  category="operations">
  <resource-bundle>
    <l10n>
      <name>IT System</name>
      <description>
        Provide information on an IT system to be deployed to.
      </description>
      <about>
        IT systems are part of environments where products are deployed to.
      </about>
    </l10n>
    <l10n locale="de">
      <name>IT-System</name>
      <description>
        Erstellen Sie eine Akte zu einem IT-System.
      </description>
      <about>
        IT-Systeme stellen Funktionalität bereit, die von Services genutzt werden.
      </about>
      <type plural="IT-Systemtypen">IT-Systemtyp</type>
    </l10n>
  </resource-bundle>

  <properties>
    <property key="projectdoc.doctype.common.type">
      <value>
        <macro name="projectdoc-name-list">
          <param name="doctype">it-system-type</param>
          <param
            name="property"
            key="projectdoc.doctype.common.type" />
          <param name="render-no-hits-as-blank">true</param>
        </macro>
      </value>
    </property>

    <property key="projectdoc.doctype.it-system.lifecycle-phase">
      <value>
        <macro name="projectdoc-name-list">
          <param name="doctype">lifecycle-phase</param>
          <param
            name="property"
            key="projectdoc.doctype.it-system.lifecycle-phase" />
          <param name="render-no-hits-as-blank">true</param>
        </macro>
      </value>
      <resource-bundle>
        <l10n>
          <name>Lifecycle Phase</name>
        </l10n>
        <l10n locale="de">
          <name>Lifecycle-Phase</name>
        </l10n>
      </resource-bundle>
    </property>
  </properties>
</doctype>

Click here to expand the Lifecycle Phase Descriptor

Lifecycle Phase (a type)

<doctype
  xmlns="http://smartics.de/xsd/projectdoc/doctype/1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  id="lifecycle-phase"
  base-template="type"
  provide-type="none"
  category="reference">
  <resource-bundle>
    <l10n>
      <name>Lifecycle Phase</name>
      <description>
        Define a lifecycle phase.
      </description>
      <about>
        Lifecycle Phases define phases that are bound to a lifecycle.
      </about>
    </l10n>
    <l10n locale="de">
      <name>Lifecycle-Phase</name>
      <description>
        Definieren Sie eine Phase.
      </description>
      <about>
        Phasen von Lifecycles dokumentieren einen Abschnitt im Zyklus von Ressourcen.
      </about>
      <type plural="Lifecycle-Phasentypen">Lifecycle-Phasentyp</type>
    </l10n>
  </resource-bundle>

  <properties>
    <property key="projectdoc.doctype.lifecycle-phase.lifecycle">
      <value>
        <macro name="projectdoc-name-list">
          <param name="doctype">lifecycle</param>
          <param
            name="property"
            key="projectdoc.doctype.lifecycle-phase.lifecycle" />
          <param name="render-no-hits-as-blank">true</param>
        </macro>
      </value>
      <resource-bundle>
        <l10n>
          <name>Lifecycle</name>
        </l10n>
        <l10n locale="de">
          <name>Lifecycle</name>
        </l10n>
      </resource-bundle>
    </property>
  </properties>
</doctype>

Limitations

We started our internal beta (although the sources are already published on Bitbucket) to check how it is working. Needless to say that at this early stage it has some limitations:

The syntax for defining sections is not final
Only one space blueprint can be defined
There are grammatical problems with the boiler plate texts (especially in German), so there is the need to run over the generated localization bundles
No roundtrip: You should not need to edit the generated files (or if you do, should not use the descriptor again)
Very simple wizards currently
No support to add CSS or JavaScript

We'll work to improve the tools to remove these limitations.

Link

Blog

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

Principles

Types of Pages

The Tool

Limitations

Posts

About

Keep up-to-date!

Powered by

Blog

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

Creating Blueprints is fun!

Principles

Types of Pages

The Tool

Limitations

Posts

About

Keep up-to-date!

Powered by