Introduction

Years ago, I was the new system administrator at the company. I had to get a handle on the multitude of systems, servers, and software. My predecessors did a great job of documenting the details in Microsoft Word. Because of the number of documents, it was hard to find stuff. It was time-consuming to keep details up to date as software and systems changed.

Then I discovered MediaWiki, the Open Source software that runs Wikipedia. An old donated PC was the host for Linux and MediaWiki. I copied the Word documents into the wiki. It was easy and natural (for me at least) to build easy to navigate links to the IT documentation. MediaWiki keeps older versions so it is easy to see the history of changes. Wiki markup is weird and unnatural to normal people but a few folks at the company took to it. The help was welcome for maintaining the IT processes and procedures. Contributors logged in to MediaWiki so we could see who made changes.

Unlike the Word documents, it was easy to search and find information. We could email hyperlinks to folks in need of support. That saved time for me and other power users. And normal folks would sometimes let us know when documentation was out of date or wrong. MediaWiki reduced the friction of sharing and managing the documentation.

I looked at SharePoint a few times. SharePoint is well integrated with Windows and Microsoft Office products. It seems like a natural extension for folks familiar with that world. SharePoint’s wiki didn’t work for me though. And the easy extensibility worked against using it for documentation. That lead to a lot of rabbit holes to get lost in when the focus should be elsewhere. Don’t get me wrong, I am very good in the Microsoft world but it felt like more friction to get things done.

Atlassian Confluence

I came across Atlassian Confluence while exploring Agile development methods. Confluence is like a polished MediaWiki.

Working together on documentation is well thought out. Instead of emailing the author about changes a user selects text on the Confluence page. A popup presents the user with the option to comment right on the page. Comments are part of the documentation. That is much better than email silos.

The real-time collaboration is great. When more than one user edits a page at the same time the changes synchronize between them in real time.

Like MediaWiki, Confluence keeps track of previous versions of the pages. Having that history gives users more confidence. They do not have to maintain many copies of a document. The history is all right there with that page in Confluence.

Embedding and attaching pictures is easy in Confluence. Users can also attach Word, Excel, PDFs and other files.

A cool plugin for Confluence is Gliffy. It is like a web based Visio for creating diagrams, flowcharts and so forth. Many times IT documentation is better with a network diagram or a business workflow. The Gliffy plugin tracks versions as well. Users have that history of changes which helps with complex diagrams.

Confluence benefits from tight integration with Atlassian JIRA. That is good if you use JIRA. JIRA is an issue tracking tool that is great for software development. Many use JIRA for business project management and managing service.

Confluence and JIRA are both available as cloud services from Atlassian. No servers to maintain.

Having time on my hands I went with installing Confluence and JIRA on my servers. Well, actually Hyper-V virtual machines running Linux. The install process is well documented. I ran into a few problems but Atlassian had intuitive help to get through them. The price made me smile. My self-hosted servers were $10 each for 10 users. That’s a good value and a low barrier for these tools.

Confluence helps my efficiency with the DRY principle (Don’t Repeat Yourself). Having the notes and documentation online means they’re available almost everywhere. And Confluence reduces the friction of maintaining documentation.