Code Comfort: Working Code over Documentation

Working software over comprehensive documentation is one of the key element of the Agile Manifesto. In his book “Software Ownership Transfer”, Vinod Sankaranarayanan provides his perspective on why documentation should not become an objective in itself for software development projects. It is only one of the tool that can be used to communicate about the software to other members of the project team.

What is working code? It’s not just the software enabling the feature to work in production. It’s the sum total of the application code, the automated test cases, and the build deployment scripts that ensure the right versions of the application can be tested and taken live. Working code begins with testable code. Working code is the soul of the application. No amount of diagrams and documentation can make up for working code. When you create a document, you are also creating an expectation to maintain that document. Ensuring that the document is up-to-date with the code can be difficult. Any developer will look for code comfort rather than what is written about the code. Hence, the primary focus ought to be on remote pairing and delivering features. The secondary objective would be to develop knowledge about the code base. Automation tests are an intrinsic aspect of software development. One of the best ways for developers to understand functionality is to run through tests. Tests are an excellent way to appreciate the functional expectations from the application. Because our program at EuroT had followed test-driven development (TDD), it aided in the ownership transfer as well.

I believe the concept of code comfort is a fundamental pivot on the traditional expectations around documentation. Documentation in software development has long been glorified as the only means to transfer knowledge. In the Agile world, we seek code comfort rather than documentation comfort. Our developers did not spend time going over high-level and low-level designs. Where something was not clear, developers used the pairing tool and did a pencil sketch of the module in question. This usually comes naturally to developers when explaining something. If the drawing made sense to be saved and shared, it was put into the work space where all the files were saved.

I do not mean to deride documentation or the need for it, but we have come to a state where documentation has become an objective in itself. In previous projects, I have been part of reviews where developers have been castigated because they are poor at documentation. In these cases, we unfortunately create an anti-pattern. Team members begin to focus more on how to document instead of actually writing code and communicating about it. At the same time, we do not allow for effort to develop the documentation. In my previous role of project manager, when I coached the team to add points for documentation, the client management rejected it.

Communication is key. Documentation is an aid to communication. At EuroT, one of the units to be transferred over was the architecture of the platform—not at the module or functionality level, but abstracted at a much higher level. This required some medium for us to articulate. There is really no code, as such, for architecture. Architecture is how the system has been envisaged. In this case, we created a couple of diagrams, but we also recorded a walkthrough of it using the diagram as a medium. This video was then uploaded onto the document repository system along with the diagram itself. Using both documentation and a video allowed us to communicate more effectively.

The trouble with documentation is that it does not convey the emotions, history, and a lot of the unstated knowledge that has gone behind making the system what it is. It especially doesn’t convey the questions around architecture. Senior developers will usually be more interested in the “why” than the “what” and “how.” Given experience and skill sets, the “whats” and “hows” are easy to acquire. What raises questions is why something has been designed in a certain way and why a different method was not adopted. A lot of decisions made over time may look silly years later. After all, systems and technologies advance at a rapid pace. For various reasons, our platform may not keep pace with evolution. Articulating all of this on paper is impossible. A walkthrough will only take you so far. The person who has lived the experience can tell a story. Capturing it on video helps pass on some elements of that story through an audiovisual medium. Ownership transfer involves transferring history, context, and thoughts as well as commitments.

Reference: “Software Ownership Transfer: Evolving Knowledge Transfer for the Agile World”, Vinod Sankaranarayanan, Addison-Wesley

Website: http://ownershiptransfer.in/