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.
<figcaption class="wp-caption-text">Page Edit Restrict</figcaption></figure>
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.
<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
<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.
-
a Markdown-like interface for editing and formatting your document.
-
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