Using Confluence as Architecture/Documentation Repository

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
Page Edit Restrict
Space Permissions
Space Permissions

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
Confluence Page Versioning

Search-ability

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

Confluence Search
Confluence Search

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.

2 Replies to “Using Confluence as Architecture/Documentation Repository”

  1. Nice summary! Confluence indeed seems to have matured as a product for enterprise wiki and documentation. My only complaint, pedantic as it may be, is that users cannot change font and size. The only way to customise font is for admin to add global style which is not ideal. I wonder if that’s by design to ensure consistent look and feel.

  2. Also using it as a documentation tool ATM. Seems to work well especially the search-ability is very useful. Also it has a lot of pre-baked templates and macros that you can insert which makes it so much easier to quickly document.

Leave a Reply

Your email address will not be published. Required fields are marked *