Solving the puzzle - Documentation notwithstanding

Share this:

In software development, we look forward to those precious ‘greenfield days’ we get in the year. The days on which we can start coding from scratch, be creative and build something from the ground up. Even if it is a single brand new cog that’s part of a larger machine. Unfortunately, we all know these days are far and few between.

The hard reality is that software engineers work on code that has already been written to a predefined design. The code might be our own from just a few weeks or even months before, but it might also be the legacy of those that came decades before us.

This means that dev teams typically work on bug fixes, change features, or add functionality to an application that they are not intimately aware of. The question is: Are we giving developers the necessary tools to get the job done, or are we sending them in blind? 

Unfortunately, the latter tends to be the case. As an industry, we are still maturing; the majority of code bases remain sparsely documented, are not built with the tenets of clean code in mind, and don’t necessarily adhere to any modern architecture setup. Getting even small changes done in such a situation is challenging to say the least. 

In my experience, we look away from finding the answer to a very basic question that would greatly benefit software development and any modernization program; How was it built? For me, this is the crux to any digital transformation project that truly helps software leadership deeply understand their applications landscape and make decisions based on hard facts.

If you cannot relate to this, let me share the following comparison.

As an avid handyman, I like to change things around the house. The latest task was to remove one radiator and relocate a second radiator to an adjacent wall. Initially, it did not seem such a difficult job as I did not want to change how the entire system works just what it looks like – merely changing the front end of my house.

Although the radiators are in plain sight on the walls of my house, the same cannot be said for the piping hidden from view. The house build quality (or lack thereof) ensures I do not have access to the mere 8cm of space below the floor to check how things are connected. Nor did any documentation survive (or even get drawn up) on how the heating/CV system was installed.

Like most developers, I am left empty-handed with the task of finding out the status quo of things in a messy and sometimes complex trial and error manner. For many developers, this means putting print statements in to find out what is happening. Whereas for me, the process was a bit more brutal and rudimentary: pulling up the floor and making my best guess.

Not only is this approach frustrating and time-consuming, but there is collateral damage along the way. A risky method of getting things done, but something that works if you have no other option. This latest DIY task left me with a great appreciation for documentation where and when it is available, as well as for those of us who are tenaciously defending the time needed to document while you code.

So here is my call out to everyone in IT: make sure you leave a trail of breadcrumbs out there. Whether it’s more extensive documentation or a high-level design with good descriptive comments in the code, in whatever form, they all fulfil that basic requirement of leaving the knowledge behind on how something was built. 

This is not just something that is to be considered a cost. Not at all. Well-documented systems allow for a faster build, quicker change speed, and accelerate time to market. Documentation lowers technical debt and the total cost of software ownership, not forgetting you’ll have happier developers too. Taking the guesswork out means the real professional can roll their sleeves up and get stuff done – and have fun whilst doing it!

Related resources