Mkdoc over Confluence for Indie Project Documentation

Like most developers, I find that I almost always have a personal side project or two that I’m working on outside of my day job. Quite often, these are just for fun, but sometimes they do try to solve a genuine problem. Admittedly, not many of these projects do see completion, but I like to document the larger ones nonetheless.

Dude, Your Code Should Be Self-Documenting!

I hear ya, mate. But can your self-documenting code explain why one authentication scheme was chosen over another? Or provide a quick summary of the tech stack being used? Or outline the project architecture and hosting infrastructure? The obvious answer here is no, it can’t; and I’d go so far as to say no, and it shouldn’t. Your code is a relatively low level implementation detail. But if coming back to a project after 6 months (or more), or giving a quick overview of the main points to another developer, client or potentially even investor, you’re going to need some kind of easy-reading documentation, ideally with some visual diagrams as required. Typically, this is where something like Confluence comes in.

What’s Wrong with Confluence?

Not a great deal! It’s a documentation and collaboration tool that I’ve used across several teams and organizations, and continue to use today. It serves teams with a budget and organizations quite well. However, I don’t recommend it for indie projects - especially ones that you might drop for several months at a time, and come back to later. This is mainly because Confluence (and Jira) will deactivate a project after 120 days of inactivity. Shortly after, your project data will be deleted. I can totally understand why Atlassian takes this approach. It is a free tier after all, so they’re not really making any money from hosting your documentation (or tickets) and there could very well be a lot of dead projects just consuming storage on their servers, costing them money for nothing. For my case though, that is a little bit of a dealbreaker.

I Get the Feeling You’re About to Recommend Me Something?

You bet I am!

If you do a quick Google search for alternatives to Confluence, you’ll find a whole bunch of options. Some of these are paid services (which I didn’t want) and some of these were free, host-it-yourself services that require you to install software, setup a database and create a user account - which I didn’t want either. What I ended up migrating to was Mkdocs, which is technically just a static site generator (like Jekyll, which I use to build this blog) that’s designed for project documentation. Essentially, you install the mkdocs command-line tool, scaffold out a doco project (which just contains a yaml config file and a directory for your doc pages) and start writing in markdown. If the doco is just intended for developers, realistically you could just commit it to the project as an additional top-level directory at the root of your repository (or in a separate repository if you prefer) and allow your future self or fellow devs to just clone the project and run mkdocs serve to view the documentation when they need to. Though technically, since it is markdown after all, they might be able to get by with just reading the markdown - though I’d argue that the rendered HTML docs are a bit easier on the eyes than pure markdown.

I did, however, find one little gotcha when it comes to installation, which I’ll share with you next.

Haha! Gotcha!

Let’s avoid this, shall we :)

On the mkdocs installation page, they mention that you can do an easy install using a package manager (chocolatey, homebrew, yum, etc.), or a manual install using Python and pip. Being a lazy Mac user, I originally opted to install it using homebrew, but ran into trouble later when I tried to install a custom theme, which can only be installed via pip. To avoid this, I’d recommend installing mkdocs using python and pip from the get-go.

And that’s all there is, really. A local install of a command-line tool and a bit of markdown, and you have beautifully styled, navigatable, searchable docs that don’t require any hosting.

Do you guys use something else for documenting your own projects? Let me know in the comments!

Catch ya!