Confluence is a perfect tool for online team collaboration. It makes it easy for everyone on the team to add information. Due to a lack of structure the team wiki may pretty fast become a place where it gets more and more difficult to add information so that it can be found in a reasonable amount of time. It also gets harder for team members to know where to add new content.

Image Added

In the last article, Finding without Searching, we examined the different ways of information seeking needs and behaviors. We came to the conclusion that categorizing information is the key to understanding and to support the users of an information system. In the context of a project the users are first and foremost the members of the teams and stakeholders with access to the project wiki.

Let's examine how to apply categories with tools provided by Confluence and projectdoc.

It may be helpful to know about the following resources prior to continuing reading this article:

1. Obviously it is recommended to have skimmed through the first article Finding without Searching which introduces some concepts of structuring information for users.
2. According to projectdoc you may have a glance at projectdoc Document for a short introduction to projectdoc documents and how they differ from native Confluence wiki pages. This article assumes that you know what a document property is.
3. If you don't know Confluence you may start learning about wikis in Why Wiki Software? Collaborate and Accelerate Productivity.

If you add a page to another page in your wiki as a child, you are building a hierarchy and therefore categorize your content. The parent relationship is quite strong. While a parent may have many children, each child has exactly one parent. And although there lies some value in defining your categories mutual exclusive, you should not feel to be bound to. But since each child cannot have more than one parent, you would need to be strict by design.

A Category enables the team to define a classification outside a single page hierarchy. A document may be assigned to multiple categories and therefore may have multiple semantic parents.

The information is attached to a category by selecting it's name as a value for the Categories property.

Image Removed

Image Added

The category is itself documented by a document. The document automatically lists all documents associated with it. The following example shows the document for the category 'AtlasCamp'. The example shows two documents attached to this category.

Image Removed

Image Added

Categories define navigation paths through your documentation. It is typically useful to define the major categories that are relevant for your team and project. Creating them adhoc usually yields inferior results.

$<Categories> = °Conference°

It is also helpful to define your category hierarchies more wide than deep.

Once you have organized the documents in your space and labelled them, it is easy to render context-sensitive links with automatic lists.

You may define queries to list all documents with a set of properties bound to specific values. These automatic lists - automatic since new documents will be automatically matched and show up in the list - are a helpful tool to define context sensitive navigations.

The following projectdoc macros are rendering automatic lists:

The basic principle behind the combination of categorization and automatic list is the open/closed principle: Your documentation is open for extension, but each individual document is closed for modification. If you add a new document you extend your documentation. But you do not need to modify existing documents. This helps you creating and maintaining your documentation as a team.

We had a deep look into tools provided by projectdoc to organize information in in Confluence spaces. Unfortunately there no not a single hard rule that can be applied on what tool to use for which categorization. But we gave same rules of thumb and offered some basics to discuss with your team.

Most of the automatic collection of information by type work best for a small to medium amount of documents for that particular type. Once your space gets larger and larger you'll probably add additional queries to establish more partitions for your space. Either you can use hierarchies (parent/child relationships) or add additional space index pages.

Creating a sound and easy-to-use organization structure for your project documentation is not an easy feat. Nor is it a one-shot endeavour. As you learn more about your domain, do not consider it a fault if you need to refactor your documentation. In fact it may be a moment to celebrate since you have worked your way to a new insight.

If you have questions or want to discuss your improvement ideas, please do not hesitate to get in touch!