Organize your spaces with generic and specialized categories.

Background Information

 Show background information ...

Organizing

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

Peter Morville and Louis Rosenfeld. Information Architecture

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.

There are three different ways for users to find information:

Searching
Using a search field to specify a query to get a list of results.
Browsing
Using links to find information that is related to the current finding to finally understand the question and find an answer.
Asking
Get in contact with someone to get support.

We can support our users on each of the three approaches. For Searching and Browsing we need to categorize our content. Either to find them through querying with search terms or by building hierarchies to browse the content.

These are the tools in your projectdoc Toolbox to categorize your content:

  1. Generic Types
    1. Category - Categories allow to set document instance of different doctypes in a hierarchy.
    2. Tag - Document the semantics of a tag. May also be used to document Confluence labels.
    3. Subject - Subject documents allow to set document instance of different doctypes in a common context.
  2. Specific Types
  3. Doctypes in General
  4. Simple Values
 

The following sections are part of a blog article.


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.

Hierarchies and Queries

 

Note that you can use hierarchies in your queries!

If you want to select all conferences (as shown in the example above), use Ancestor Queries.

To list all documents with category 'Conference' or any subcategory, use the following constraint (e.g. Display Table Macro):

$<Categories> = °Conference°

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

Categories over Topics

 

Whenever you think to create a topics page for collection resources for a given topic, consider to create a category. The category document is usually good place to define and collect resources for a topic.

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.

Categories or Tags?

 

It is not always clear, when to create a category and when to use a tag. There is no hard rule for the selection. Every project has different documentation needs. Nonetheless some ideas on this topic.

As a rule of thumb you could use categories to define the domain that is relevant for your project. Usually this works best if the team creates the project context in one or two short timeboxed sessions. Then every team member has visualized what is relevant to be documented or tracked and where. Categories are naturally hierarchical in nature. Use them and try to build flat taxonomies. Think of categories as a tool to organize the menus for your wiki space and therefore to control the navigation.

For instance, if you have a number of marketing channels you want to have quick access to (information on how and why your team uses them), you may define a tree rooted in

  / Marketing / Channels

and define subcategories like

  • Blog
  • Speaking Engagements
  • Offline Events

On the other hand use tags for labelling. Typically tags are not hierarchic or have a one-step-deep hierarchy to group related tags. Think of tags as a tool to link to related resources in a given context.

Tags could be something very simple as Recall or Feedback or define a list of related topics you do not want as categories (like Architecture, Community, or Delivery).

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.

Documents and Records

 

It is usually a good idea to separate documents (which will be updated) and records (which will not be updated). If your team collects information on a topic, that document will be updated whenever a new relevant piece of information is discovered. On the other side minutes, for example, are typically not updated.

In addition to that you also have investigations in unknown territory where you want to share the actual state of knowledge with your team. Also consider to separate these work spaces from spaces where your organization scheme is carefully designed. Allow teams to work without constraints while being on a discovery mission. Limit the application of documentation rules to spaces that contain information that is worth to be maintained over the project's lifetime.

Specific Types

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

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.

 

A type is defined by the name of a value for the Doctype Property and a Confluence Blueprint.

Use the Name List Macro, Name Body List Macro, or the tag-specific Tag List Macro to define values for a document type in its document properties table.

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 semantic 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.

Category or Tag or Type?

 

When should you use a category / tag and when a specific type? Categories and tags are generic by design. This implies that they have valid semantics on any document type. A category or tag should be valid for use on documents for  a person, a topic, or minutes. Types are specific and therefore defined for a single doctype.

Note that there are more generic categorization options than categories and tags: The Audience Property allows to define the target group for your document.

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.

Encoding Titles

 

Every page title has to be unique within a space. Sometimes names of categories, tags, or subjects may collide with titles of other pages. You may have a category named "Continuous Delivery" and also a resource that refers to a book with that title. You may have a tag "OOP" before you find out that you have a page referring to a conference with that name.

To differentiate the titles of organizing documents from those with specific information, you may prepend the page title with a special character. The name of the document (defined as a document property) will not use this prefix. The name is not limited by the uniqueness constraint since the name of the document is only unique within its document type (and this constraint is not technically enforced).

Typical prefixes for types are:

  • # for tags
  • / for categories
  • § for subjects
  • ? for open issues
  • ! for decisions

You may define any number of encodings, but be aware that they have to be recalled by the authors. So it is typically a good idea to limit them to tags, categories, and subjects. If you think you do not need them, go without prefixes!

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.

Hands-on Steps

Create and use Tags

  1. Remove the homepage for tags from the 'My Workspace' space to collect documents of type Tag on the delegate space only
  2. Note the visual clue (italics) for readers to know that the tags are defined outside the space
  3. Create a tag document with name 'Test'
  4. Edit the Display Table Macro in the Documents section, set Space Keys (plural!) to @all
  5. Save the macro
  6. Save the page
  7. Open the 'My Team' document
  8. Add the Test tag
  9. Save the macro
  10. Save the page
  11. Note that the tag named 'Test' is a link
  12. Click the 'Test' link

The tag document automatically lists all documents being associated with this tag.

Create and use Topic Types

  1. On the 'My Workspace' homepage click 'Types'
  2. Click on 'Topic Types'
  3. Delete the Topic Types homepage to delegate all topic types to the delegate space
  4. Create a Topic Type
  5. Create a topic type named 'Book'
  6. Change the Display Table Macro in the section 'Topics of this Type'
  7. Save the page
  8. Go to the 'My Team' document
  9. Add the topic type 'Book' to the topic (just for this exercise's sake (smile))
  10. Save the macro
  11. Save the page
  12. Click the 'Book' link

The document of the topic type 'Book' automatically lists all topics of this type.

Next Step

Continue with the next step: What's next?

Content


Next Step What's next?Previous Step The Workhorse Macros