Using Confluence as Architecture/Documentation Repository

August 08, 2017

Tags: Architecture  Confluence  Documentation  TOGAF 

I’m starting on a new project so I need to document the decisions that I am making in the design and processes. After evaluating a number of platforms or methods, I have concluded that using Confluence was a good fit, so here I summarise my reasons for this, I hope you find it useful:

Permission Management

One of the main things for me was making sure that only authorised people can view and change these documents so permission management is very important to me. Confluence gives you the ability to lock a whole Space to a group of users or individual pages. I used the first approach so I created a team in Confluence and gave this team a Edit permission on the whole Space, everybody else (who is authorised) can view

It’s always better to be inclusive, so if a team member have some ideas to propose or want to change something, they can add a comment on the document and one of the authorised users would make the change. This way we have all the discussions around what went in and the rational behind it.

Page Edit Restrict<figcaption class="wp-caption-text">Page Edit Restrict</figcaption></figure>

Space Permissions<figcaption class="wp-caption-text">Space Permissions</figcaption>

Versioning Management

Changes to pages and posts are saved in Confluence with their history of changes. This makes it very easy to look up any page and see how it was changed? by whom? and at what time? I have also installed this plugin (need to pay for it) which allows me to keep multiple versioning of the same page. This is very important for documenting API/Contracts so that you have all the documentation of all versions in one place.

Confluence Page Versioning<figcaption class="wp-caption-text">Confluence Page Versioning</figcaption></figure>

Search-ability

Search is a built-in function of Confluence so you get that out of the box

Confluence Search<figcaption class="wp-caption-text">Confluence Search</figcaption></figure>

Users (stakeholders) accounts

This was a big plus for us as the organisation already has Confluence and they already use it for other areas of the business, so it made it easier to adopt by the team. You could use the cloud-hosted version of Confluence, in which case Atlassian would charge you per user account. Or you could host the application locally and you can manage and create/remove your users.

Ease-of-Use

There are really 2 things that I enjoy using in Confluence.

  1. a Markdown-like interface for editing and formatting your document.

  2. You can export document to other formats like a word document, which sometimes important when you trying to communicate a document to any stakeholder who is not a tech savvy and would not want to touch Confluence 🙂

Extensibility

Plenty of plugins (free and paid) to choose from, so most of the time you would fine what you are looking for as somebody has already developed a plugin for it.

That’s it for me, I would love to hear what you are using, so do let me know in the comments.

If you have a comment, feedback or a question, I would love to hear from you