Knowledge is the lifeblood of the system

Nov 18, 2014

Picture this. A developer has written a large proportion of code for your product and has recently left your team for another company and a customer has requested a new feature. It’s the first time you’ve looked at this area of code in detail, and now you need to start to try to find the wood from the trees so that you can make the changes you need to make. But first, you need to understand how it works and it’s a complex area. How much time you think it may take to deliver this, where do you start? Most likely, you look straight at the code.

This scenario happens a lot. If you consider an average working day for a developer, and the large number of third party libraries that are available, you probably already spend a considerable percentage of each day trying to understand someone else’s code. You’re either trying to use something they have created, adapt it to a situation you have to solve, or fix it when a problem arises. Apart from looking at the code, you’ll probably search the web to see if you can craft together solutions based on those provided in online communities. Finally you might try and contact the maintainers of the code if you’ve exhausted other options.

In fact, most of the time, understanding what the code is doing isn’t the problem. Its trying to understand why its doing it that is the challenge. Because if you change something without understanding the 'Why', you may create another problem somewhere else. Its like trying to fix any system without an understanding of how the dependant parts interact. And the 'Why' for a particular piece of code depends on what the developer was thinking at the time. If you reflect on your own internal dialogue when you develop a piece of code, you’ll notice that you’re thinking about all of the possible uses for this code. You’re thinking about its limitations, how it might handle failure cases, performance, security, scalability and more, the list is endless. That’s quite a list to try to understand just by looking at ‘what’ someone created.

So we have to ask, why isn’t documentation of how a solution was designed and why it was designed that way given a higher billing? Well, on the face of it, the documentation of the thinking behind how something was created has little business value. The percentage of time taken to understand someone else’s code, is in most cases seen as just part of the job and the times when it critically affects a team’s ability to progress is probably far and few between. But that doesn’t mean that it’s the way it has to be. Understanding of the how something has been designed and why it was designed that way is a valuable piece of information; a key part of the knowledge of the solution. Without it, we will spend time trying to reconstruct that how and why by looking at the what, the code. And if we start to make that visible, it can inform us of what we need and when.

Our suggestion here, is to firstly make this time visible. Start to record the time taken to analyse and understand someone else’s code when investigating what changes need to be made. Next, answer the question, ‘what would really help here to cut this time?’ And then find a way to provide that with the lowest amount of effort possible. In most cases with clients we have suggested creation of lightweight knowledge bases, for example wiki pages for what features are, pieces of the system that support them and how and why these were designed in the way that they were. Capturing this information when it is created, by the developer when they are writing the code, helps preserve the how and the why. And that not only helps preserve the life of the system. Writing it once, saves many developers time trying to reconstruct it many times later, saving time for more important things, like developing features desired by paying customers.


To learn more about about how these documentation strategies might work for your specific team and working environment, please Contact Us. And sign up for our newsletter to stay informed of new articles, news and events occurring for Inviting Futures.


To receive more free, regular productivity related tips, subscribe now!