Introduction

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.

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.

Prerequisites

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.

Tools

In a project team members usually have not much time to organize and reorganize information. So we are looking for some time-savers that support teams on creating project documentation collaboratively. We will not dive into any specifica here, but investigate generic approaches that are helpful for any project or communication need.

We examine the following tools:

1. Categories
2. Tags
3. Subjects
4. Specific Types
5. Doctypes in General
6. Simple Values
7. Automatic Lists

Knowing these tools for categorizing your information will improve your documentation in aspects of extending and navigating.

Categories

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.

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.

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.

Tags

Confluence allows to tag documents with labels. This is an adhoc approach that is easy to use. Unfortunately labels are usually not documented. So authors may use a single term differently or use different terms for referring to the same thing.

The Tag document type allows to add semantics to a tag. To have a lightweight start to define a controlled vocabulary. You may also use them in the context of folksonomy, but be prepared that this may not work out great without effort.

The advantage of folksonomies isn't that they're better than controlled vocabularies, it's that they're better than nothing, because controlled vocabularies are not extensible to the majority of cases where tagging is needed...

Peter Morville and Louis Rosenfeld. Information Architecture

If you use the Tag List Macro then Confluence Labels are automatically considered tags in the projectdoc world. While labels are automatically visible to readers, tags may be hidden.

Subjects

While a document can be associated with any number of categories and tags, the subject is defined to be exclusive (although there is no technical constraint that enforces this). Think of a subject as a workspace to hold information for a specific project or spike. Subjects may be temporary. If you conduct a spike you may add all insights to a subject. Later in the iteration you have more information on the matter and may apply the collected resources where they belong.

Subjects are typically not hierarchic, but if it works out well for you, you can organize you subjects as you can do for categories, tags, or any other document type.

If you expect to work on a subject with a larger team, consider to create a separate workspace and link from the subject document to that space. This is especially useful to get your team running without having to consider where to place a new piece of information. After the spike is run, the team decides which information will make it to a topic space and which is only an intermediary result to be archived with that space. This helps to decide which information has a stakeholder and is assumed to be valuable on the long run. Every document is a liability that absorbs maintenance costs.

Specific Types

For every document type you may define specific types that are only valid for this type. Think of

• topic types or experience levels for topics
• module type for modules
• resource types for resources

Whenever you have specific categorization in mind for a group of document instances, consider to define a new specific type. But every type requires additional work! Be sure to discuss the usefulness of additional types with your team. As often, less is more.

Other than the categorization types discussed so far, specific types are key-value pairs. The name of the type is the key.

If you define a new type, this type typically names the reasons and stakeholders that support this type.

The page with the type instance definition usually also lists the documents associated with this type. Therefore each instance of a type is a natural hub for information tagged with this type.

Types may be semantical or technical. Albeit semantics are usually more helpful than pure technical categorization, due to their combination they can form a powerful tool to categorize content with automatic lists.

Every Doctype is a Type

There is nothing special for a doctype to be a type document. So every doctype supports your organisation system. For instance you may

• use Glossary Items to define the terms of your domain and relate information to them
• collect information according to Organizations you are partnering or competing with on your project
• organize publications by their Authors via the Person Doctype.

This approach is very generic. Use what works best and naturally. But you need to discuss and communicate your strategy within your team.

Simple Values

Simple values do, in opposition to all the other mentioned categorization tools, not refer to document that documents the semantics of the value. Examples are the Iteration Property or the amount of story points of a user story.

Simple values are simply a tool to define metadata for a document. A doctype usually defines the properties for all document instances. Authors are free to add any number of a additional properties, but doing so may hurt the principle of similar structured documents. Similar structures support authors to create documents and makes them more easily readable by users.

Automatic Lists

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 query matched no documents.

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.

Conclusion

We had a deep look into tools provided by projectdoc to organize information 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!

Introduction

Users of an information system have an information need. It's the information architect's work to help these users "to complete tasks and find information in blissful ignorance of [their] labours" (Peter Morville and Louis Rosenfeld).

Information needs to be organized to be helpful to the users of a system. And there is even more to it:

We organize to understand, to explain, and to control.

Peter Morville and Louis Rosenfeld. Information Architecture

This is very important: Since we work in teams of software developers, we need to get used to the fact that communication and organizing information help us to understand our domains better. Finally we yield better results: happier users, happier stakeholders, and happier teams.

How can information architects help users to find without searching? How can team collaboration on information help to understand the domain more thoroughly?

To answer this questions we will take a theoretical and a practical approach.

• In this article we examine the types of searching and ways to organize information. This is the basis for our practical considerations.
• In the next article we will provide a more practical approach on how to apply this theory on a Confluence wiki using projectdoc. We look from the perspective of software development teams to create their project documentation collaboratively.

The goal is to learn how to organize project information effectively. While we aim at software developers with the need to document their projects, software and system architecture, this article is probably also relevant for other teams that work on other kinds of projects collaboratively.

Seeking Information

Searching for something you know is a very different behavior than browsing for the unknown.

Peter Morville and Louis Rosenfeld. Information Architecture

First we - as providers of information - need to understand the different types of information seeking users perform.

Enable Seeking

We are looking for a solution for this notion of finding without searching. We need to present a link to a path to pursue for all questions a user may have in a given context. Sure this is not a reachable goal, but this requirement defines a motto that gives us a lot of direction. Without creating an information overflow on the user's side we are up to provide pointers to related information.

What can we do to support our users with their task of information seeking?

• In the case of Searching we attach a search field to every context and employ our wiki's full text search capability.
• According to Asking this is also quite easily accomplished: we add a reference to a person (with her address and contact options) who assist the reader in a given context.
• The amount of work to support Browsing is much more. We need to create relations between the information we present in our wiki. These relations will help to navigate through the wiki spaces.

Classifying

On classifying information we also relate them. With each relation we enlarge our web of information, enabling users to travel from one topic to another related information.

When we define an organization structure we often use the top-down approach. We arrange the information hierarchically and speak of taxonomies.

The beginning of all understanding is classification.

Hayden White

In the sense of Aristotle's Definition of Definition this process of classification makes us understand the terms of our domains. To define a term we first have to put it in a broader context, that is: put it to the class it belongs to.Then specify what distinguishes it from all other elements in this class. In the context of a taxonomy the upstream terms are generalizations, the downstream terms specializations.

Labelling information is a bottom-up approach for organizing. Every resource of type 'Podcast' has something in common. Every topic labelled with 'Java', too. Although these classifications are rather generic to be useful by themselves, they help to specify quite specific queries as in "List every resource of type 'Podcast' labelled with 'Java'".

Once the information is classified, it can be applied to enable browsing. Use automation to render links to relevant information on search criteria. In Finding without Searching - applied! we will have a look on how Confluence and projectdoc supports us on this task.

Conclusion

This short article puts together the types of information seeking and the seeker's behaviors. We then had a look on how to enable users to seek information. While providing means to search for a particular term or ask an expert may be accomplished easily, relating information is a more complex task. But once classified, we can create links to related content more easily.

Working together as a team and organize our domain information will support us to understand our problem domain more thoroughly and to create a proper solution.

Next we will see how to apply this theoretical approach to your Confluence wiki using projectdoc.

References

If you like to learn more on information architecture or Hans Jürgen von der Wense, read:

• Information Architecture by Peter Morville and Louis Rosenfeld
• Information Interaction Design: A Unified Field Theory of Design by Nathan Shedroff
• The quote "I find and find, without ever searching" is from Werke 2, p. 1232: "ich finde und finde, doch ohne jemals zu suchen", Hans Jürgen von der Wense