04 Dec 2014 Confessions of a Documenter

I’m going to confess something. I’ve been harbouring a terrible secret for the last few years. It’s something that I’ve tried to keep hidden away from my peers for a very long time so as not to be labeled as “that guy“. Something I’ve kept buried deep in the depths of my darkest closet. Ok, maybe I’m being somewhat melodramatic. Pray tell, I hear you say, what is it?!

Well, it’s that I enjoy writing documentation. From the lowliest code comments through to high level architectural documentation. I enjoy it all.

Yes, you read that right. It wasn’t a typo. And not just that, but I also believe that it’s mighty important in our profession. Take a moment to let initial shock subside.

Documentation is normally treated as being the bane of our existence as software engineers. The boring, mundane and monumental pain in the ass job that nobody in the team ever wants to do. The task that’s usually given to the last person that broke the build, or forgot to merge their changes over from the development branch – the outcast of software development.

So, why on earth do I like to write documentation if that’s the case?

It Routinely Makes Me Appreciate What I Really Love to Do

I love to solve problems by writing code, and ultimately building software solutions. However, just recently I was handed the rather important task of reviewing and updating the complete high level architectural documentation for a large enterprise solution for one of our clients. No, I hadn’t broken the build. But instead, get this, I actually volunteered. Gasp!

The software had been initially built about ten years ago and since that time had undergone numerous changes, as all software does, and had passed through the grubby hands of dozens of different developers. This wasn’t just a short one or two page document that needed to be updated with a few new shiny diagrams in order to align it with what was actually running in production. No, this was a sixty page technical document and it was in need of a complete overhaul. Over the years it had gathered more dust than my Matrix Reloaded DVD.

It took me almost three weeks from start to finish during which time I did zero development. None. Nada. Zippo. I was just reading and writing documentation all the livelong day. I went down a rabbit hole never to be seen again and didn’t touch a line of code for the whole time – except to fix that bug I wrote which broke the build. Whoops!

But when it was all done and dusted and I went back to actually developing, I was once again struck by the appreciation of being in a profession that I truly enjoy. Developing software was something that resonated with me from the very moment I wrote my first line of code back in 1990. I was hooked. It’s something I still throughly enjoy, and writing documentation routinely makes me remember why that is.

It Allows Others to Better Understand My Code

Even if you think that you write the most succinct, elegant and beautifully crafted code on the planet, someone else might think that it just plain sucks. I’d like to think my code is well structured and readable. For one, I try and follow the guidelines from Uncle Bob’s Clean Code (if you haven’t read it, I’d suggest you do so immediately) whenever I can. Secondly, I’ve been coding long enough to spot code smells early on in development cycle e.g. when a method/function is too long, or if it just doing too much stuff and it’s in need of some refactoring. And finally, I frequently ask my colleagues to conduct code reviews which are invaluable.

Nevertheless, just because I find my code tight and easy to read doesn’t necessarily mean someone else will. I don’t buy into the whole “if you need to document your code then it isn’t any good” mentality. That’s just plain rubbish. It’s naive to assume someone else – or even me a few months down the track – will be able to read and understand it.

However, excessive use of documentation can be an immediate warning sign. One of my favourites from Coding Horror is this great post from 2008 about that topic. It’s a great read all the way through, but for me it’s this part which is hits the nail bang on the head.

“While comments are neither inherently good or bad, they are frequently used as a crutch. You should always write your code as if comments didn’t exist. This forces you to write your code in the simplest, plainest, most self-documenting way you can humanly come up with.

When you’ve rewritten, refactored, and rearchitected your code a dozen times to make it easy for your fellow developers to read and understand — when you can’t possibly imagine any conceivable way your code could be changed to become more straightforward and obvious — then, and only then, should you feel compelled to add a comment explaining what your code does.” – Jeff Atwood

While this might seem extreme, and I agree that it is to a certain degree, it’s still great to use as guideline when documenting – develop your code to be a readable as humanly possible and then document it. Finally, it should be concise, informative and truthful. “Truthful?!” Yes, let me explain.

One of the biggest and probably the most of obvious of all documentation caveats is that code never lies, but documentation can. You’ve heard it a million times before. You’re sick of hearing it, I know. But I’ll say it anyway; keep your documentation up to date! If it’s not given the attention it deserves then it’s about as useful as a chocolate teapot and can grossly mislead others who read it.

It Forces Me to Become Familiar With Other Areas of the System

To write about something means you must first understand it. All software engineers are human – contrary to popular belief – and being human we all possess this one common characteristic; that what we don’t understand we fear. It’s natural. But that need not be a negative thing. In fact, quite the opposite. It can drive discovery and encourage us to challenge by asking questions.

Drawing on my previous example once again, prior to updating the high level system documentation there were areas of it that I had just been on the periphery of. I had just enough understanding of those systems to allow me to get on with my work without ever having to fully understand how they worked or were wired together.

Whether it was the spagettiosity of the code, my lack of specific domain knowledge for a component or the overuse of acronyms spattered everywhere that I had to keep Googling, I just wasn’t comfortable with them.

But by undertaking the task of updating the documentation, it made me become much more familiar with those areas. I didn’t need to sidestep any more tricky questions, or reply with “let me get back to you!” while I tried to figure out what something was. It turn, it instilled in me a better feeling of confidence about the system as a whole, and some “ahh, that’s what it is!“, or “ahh, that’s how it works!” moments rang out in my head.

In other words, writing the documentation forced me to understand the whole system and not just the areas I worked on. And in software engineering that is a very good thing.

Wrapping Up

Like I mentioned earlier, there are many different forms of documentation. All too often we allow it to be overlooked, or to be brushed under the carpet. Sometimes it becomes relegated to a nice-to-have, and we pass a blind eye to the scarcity of it in our projects. Out of sight, out of mind.

But imagine this scenario; you finally get around to buying that new top of the line washing machine that you been hankering after. You’re so proud when it arrives that you tear open the packaging so you can wash your dirty undies only to be confronted with the fact that it doesn’t contain a manual. You would be pretty annoyed right? But we know that would never happen of course.

Software is an intrinsically complex subject matter so documentation should be treated as equally important in the development cycle just as, for example, unit tests are. There’s a massive disconnect between documentation and the software we build, and there really shouldn’t be.

It’s time to confess and renounce your sins of not documenting.