Documentation is Key | HavingATinker

At the time of writing this post I had been at my position for around 6 months, and was still learning some of the bespoke systems that had been written in-house. To help gain a greater understanding of the infrastructure and their relationships, I was tasked with fleshing out the documentation that’s in place, as well as creating docs for the systems that haven’t got any.

While documentation can be tedious I found it hugely beneficial from a learning perspective. From my experience (doesn’t mean I’m right), good documentation should be light and give you a brief overview of whatever you’re covering. It should provide you with reference material so if you forget anything it’s written down somewhere, and will help with any sort of onboarding/learning process.

Markdown#

While there are multiple Markup languages, I’ve chosen to write and become somewhat proficient with Markdown. It gives you the ability to write out documentation that’s a little more readable, and bit better organised instead of just blocks of text.

I use adam-p’s Markdown Cheatsheet for reference when writing any documentation and would recommend it to anyone.

Diagrams#

“A Picture paints a thousand words” - Some dead person

While it may take a little more time to make a diagram, it’s a fantastic way to create a visual representation of whatever you’re documenting. It gives you the ability to gain an understanding at a glance of what talks to what, and how it’s set out.

I first started using Google Drawings which fulfilled it’s purpose, however it can be cumbersome to use and in all honesty quite ugly.

That’s when I found Cloudcraft. Cloudcraft is only geared around AWS but due to it only doing one thing, it does it well. It has functionality to link up with your AWS account and create the infrastructure you have specified in your diagrams, but it comes at a cost. The free version works well for the smaller diagrams but in order to create larger ones, you’ll need to go for the paid subscriptions which in my honest opinion is extortionate (basic on starts at $49/mo).

Here’s an example Cloudcraft diagram:

Alt Text

Table of Contents#

To make your documentation that little bit easier to navigate, it’s worth adding a Table of Contents.

In Bitbucket Markdown files you can simple add:

[TOC]

In GitHub Markdown files it’s a little bit harder to do however, fortunately due to the ever amazing open source community there’s a tool called gh-md-toc. Thankfully a golang based implementation has been created for Mac OSX and Windows too.

Here’s an example of a Table of Contents that’s been generated by gh-md-toc:

Table of Contents
=================

  * [Markdown](#markdown)
  * [Diagrams](#diagrams)
  * [Table of Contents](#table-of-contents)
  * [What, Why, How](#what-why-how)
  * [README](#readme)
  * [Wiki](#wiki)
  * [Common Issues](#common-issues)
  * [Document as you go](#document-as-you-go)
  * [Conclusion](#conclusion)

What, Why, How#

I’ve stolen this idea from a previous work place, which was probably stolen from somewhere else, however I’ve found this implementation really useful.

When you’re writing up your docs, you just need three things:

What - Description of what the tool/system is
Why - Explanation of why it’s needed.
How - How is it implemented, and an overview of how it works.

Each point isn’t particularly detailed but it touches on each part at a very high level. Each section’s (What/Why/How) usually around a few paragraphs long so it doesnt have to be massively indepth.

README#

By this I mean the actual README in the repo itself.

Whether it’s your Puppet repo or an in-house written tool, you’ll want to write a README to give you a deeper understanding of how it works, and how to utilise it.

Wiki#

The Wiki will then act as a centralised, over-arching documenatation platform which is your first point of call for reference. The individual wiki pages then point you to the relevant README’s to give you a deeper understanding.

Ultimately the Wiki helps you gain a base understanding and then points you in the right direction.

Common Issues#

I also use Wikis as a way to make a note of typical issues and the solution to them. This then means that I can just search for the error mesage or issue and find the solution quickly without having to remember everything. This then also helps prevent the issue of being a single point of faulire, the SPOF being you and your knowledge of the issue.

Ultimately my memory sucks and it helps remedy this by noting it down and sharing the knowledge.

Document as you go#

As obvious as it sounds I’ve found the easiest way to document, is as you go. Typically once I have finished writing a new tool or implementing a new system, I write up the accompanying README/Wiki while it’s fresh in my mind.

If you keep this mindset, your documentation base will grow as your infrastructure does and everything will be covered in some sense. It’s very easy to get lazy and not do this however, you’re not only stuffing yourself but you’re also going to be causing your team issues further down the line too.

Conclusion#

A fair few times I’ve had conversations around documentation and the same reservations come up, the main one being “But it just goes out of date!”. Granted, yes it will but this doesn’t mean you should never do any! If not for your own sanity, think of the others around you. This then means you need to document smarter, not less e.g. a light Wiki and README relationship.

Another argument I hear is “But the code is documentation!”. Again, in a way yes, but what if the tool is written in Scala and I’m a Python guy. Are you expecting me to understand the innards of the tool/system when I can barely understand the language it’s written in? The Documentation around it, whether it’s in the README or the Wiki should just tell me what it does, not what each function or method does. I want to have an understanding of what it is and it’s components at a glance.

All in all I’m in favour of documentation (as you may have gathered), but it’s just a case of keeping on top of it, and implementing it in a sane fashion as outlined above.