An approach to documentation

Documenting code when appropriate need not even be mentioned as it' s something we should all be doing before merging back to master. Here I refer to documenting everything else.

Document, why?

I tend to document things I don't do frequently enough to burn into my long term memory but I do frequently enough that googling all the steps every time becomes an annoyance, more so if the page I used the previous time changes or doesn't come up in the results and I have to work out the same stuff over again. Unfortunately this is something I had to learn rather than figure out from scratch.

I may decide to re-image my computer, or I may work with a client whose policies mandate I use their equipment for security reasons. Regardless, I end up sitting in front of a pristine machine with nothing usable on it (besides notepad, paint and windows explorer on a windows machine).

I then have to remember all the tools I'm used to and need in order to avoid the scenario of figuring out the set up for some proxy at 6pm in order to test some change to the authentication model before committing.

Document what?

Anything you can think you need to do your work, this includes:

• Environment setup and configuration: be it windows or linux, a raspberry pi, they all need some tweaking, partitions, paths, fonts. Vagrant, Docker.
• Tools: diff tools, editors, chrome, gitbash, conEmu.
• Development: IDEs, languages. maven, npm.
• Infrastructure: ActiveMQ, mongo, Db.
• Scripts: complex SQL queries, back ups, log monitoring.

So in fact, anything you would document if you were part of a team within a company. You should aim to be as efficient as the best organisation you have worked for, there's also have the added benefit that as it's you, a method can simply be ditched if you don't like it.

Document? Where?

Well, you could write it all down in a notebook and for some things, that's probably the best place; it's unlikely you'll set up a wiki for your parents, although having said that my dad prefers to keep everything in a massive wordpad document, and it works for him.

But such cases aside it's worth considering tools similar to those you find in the workplace, sure a full CMS like confluence is going to be a bit OTT -unless you enjoy system maintenance in which case it's probably a good excuse to set one up.

Wikis

For me a wiki seemed to be the best option and over time I have gone through a few, not because I'm fickle but because hosting providers are, still it means I can talk bout some alternatives:

• Moin-Moin: a clean, tidy wiki written in python. It's self contained, needs no database and includes authentication, my clear favourite, but I can't find anyone to host python scripts.
• Dokuwiki: a bit uglier than Moin-Moin and needs a database, but it's available on the majority of hosting providers. I was quite happy with it until my provider applied the tightest security settings I have ever seen, documenting a simple SQL query became impossible as the service thought I was trying to get away with some SQL injection naughtiness.
• Github: the ugliest of the lot, the sidebar does nothing but take up screen real state, it does however, allow you to document anything you want to and backups are dead easy.

Documenting life?

As I said earlier I use a wiki to keep information that is infrequently used but cumbersome to remember, this extends beyond my own needs and work requirements, you can use it anywhere in your life you have the same problem:

• What if the boiler needs topping up while I'm at work? well it's there on the wiki,
• radiator needs bleeding,
• the router needs rebooting (print this one off or you won't get to the wiki),
• the printer needs to be configured on a new device,

well you get the idea, so what are you waiting for, start documenting.