5 Great Things About Documentation

Like many software developers, the majority of my career has been spent on maintaining and enhancing software developed by somebody else. Too much of the software I have worked on has had little to no documentation leaving it to me to figure out what a complicated section of code does, the reasoning beyond unusual implementation choices or how to perform common tasks.

No wonder brownfield development is so unpopular amongst programmers.

I think the reasons that software developers tend to avoid documentation is that expressing some programming concepts can be hard, time-consuming and the perception that it will add little value. It’s easy to justify not leaving any documentation when you’re under tight time constraints or find it challenging to express complex concepts, especially after using all of your mental energy on a particularly tricky programming problem.

Here are 5 reasons why every software developer should consider writing documentation:

1. It Can Brighten Another Person’s Day

I happened to stumble over instructions on how to build and distribute a Xamarin app that I wrote a couple of years ago which I completely forgot about. It made me laugh. At the time I wrote this Xamarin seems to have been extra temperamental, and I had forgotten the struggle it was sometimes to actually build and distribute this particular app.

  • Bump the version number.
  • Make sure it’s in the release configuration.
  • Archive (maybe do a clean and build beforehand).
  • Swear because it’s not working.
  • Distribute App. Ad-Hoc distribution and manual uploading seem to work best.

Documentation doesn’t have to be dry and boring. Just adding a little bit of colour makes things a little more interesting to you as the writer and to others as the reader. If somebody had to build and distribute that Xamarin app and had trouble maybe they wouldn’t feel there weren’t the only one to suffer the same frustrations and instead had an ally.

2. Documentation Can’t Replace You

Just because you leave document doesn’t mean that you will be less valuable to your co-workers.

It allows others to find a solution for themselves via the documentation, and if they have trouble then can still seek your help. But don’t bet on this happening :-). People will still come to you and ask the same questions. At least then if you don’t want to answer them you are able to tell them to RTFM.

3. Documentation Doesn’t Die With You.

In case you leave the organisation, or the worst happens, documenting critical processes and information means that the organisation is protected. This is a great way to make sure you are remembered for something good when you leave.

4. Reach Better Solutions

If code is difficult to document that might signal a larger problem. Expressing solutions in words and code should have a comparable degree of difficulty. If the code is trying to do too many things, in violation of the single responsibility principle, then trying to write documentation about all the things the code is doing is going to as assessable as a PhD thesis.

Documentation should communicate things as clearly and simply as possible. If you’re are having problems writing the documentation this could indicate unnecessary complexity in the code. Because we need to write simple documentation we are forced to also simplify the code which is often a better overall solution.

5. It Might Make Someone’s Life Easier

You could be having a really bad day, where it seems like people are constantly throwing obstacles in front of you. Last Thursday I thought I would have to jump a number of hurdles just to replace one Word document on a client’s server. Lucky for me, someone had the foresight to leave documentation: Enter Brad! I was delighted to find that Brad had left detailed documentation which removed all the hurdles allowing me to focus on replacing that one file.

Thanks Brad!

Even though it may seem like a time consuming and unnecessary task, documenting your code can be of great benefit to you you and the devs that come after you. It doesn’t need to be perfect. Just like software, documentation can evolve over time. 

Do your future self a favour and document something today!

Leave a Comment