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 software 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 code 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/

Additional references on software documentation

* How to write software documentation

As a software developer or engineer, there is a magical feeling that comes from releasing open-source code. The feeling is a mix of terror and excitement. You’re eager to tell the world about your new project but despair at where to start. Even professional writers know the mixed emotions caused by a blank page. Good software documentation helps relieve that fear. So, have no fear! Use this guide to document your first open-source project for public release.

* 7 Best Steps For Writing Good Software Technical Documentation

The manuals, tutorials, and other documentation materials cover a software product’s development, functionality, and use. It is just one type of technical documentation among many. Software documentation serves the straightforward goal of streamlining communication amongst all stakeholders engaged in the project. We have shared all the main steps below to help you write effective software technical documentation.

* Software Documentation: What Customers and Contractors Should Remember in 2024

Technical documentation for software deserves the attention of everyone involved in producing and maintaining IT products: developers, customers, and technical support staff. In this article, we will go over this issue, comment on best practices, and provide a number of relevant practical recommendations to consider when working with technical documentation. We hope that you will be able to compare your own experiences with our thinking on documentation, and be able to take something away that will help you in crafting your own.

* What is Software Documentation?

Software documentation is a collection of written materials describing how a software product works, how it is developed, and how users interact. It serves as a reference for developers, end users, and stakeholders by providing essential details such as installation guides, technical specifications, troubleshooting instructions, and API documentation. Well-structured documentation improves software usability, streamlines development, and ensures effective team communication.