How Much Documentation Do You Really Need?

Documentation is often bundled into a statement of work (SoW) and becomes a necessary document that sits in with a contract. They are often produced by analysts, who consult with stakeholders and then often define with meticulous detail what the requirements, exact tasks, needs, and everything else in between are.

At first, it seems logical to have such a document, mostly for verification and legal purposes. However, on a software development level, this methodology of documenting everything in such granular details embeds the monolithic method of implementing a waterfall workflow.

This creates a rigid approach to software development that doesn’t give much room to respond to change or enable developers with the ability to rapidly prototype a solution. 

Requirements are often also one-sided and unvalidated, leaving the business more vulnerable to bigger failures — not because the developers haven’t delivered, but rather because the intended audience didn’t respond as expected to the software. 

The Diminishing Returns of Over-Documentation

The more documentation you begin with, the more diminishing returns you are receiving in actual value. This is because the time it took to write the documentation prior to any development work is a sunk cost. There is nothing produced from it yet, nor is there any guarantee that the project will ever commence either.

The more documentation there is, the more time, resources and money it takes away from other endeavors. The opportunity cost increases as the document becomes more detailed, reducing the business’s ability to be truly agile and pivot to customer and market demands. 

This is because the custom software is a solution based on pre-defined requirements rather than one that is reflective of reality and true business needs. 

Discovery of needs often comes during the development phase and extensive documentation locks the business in on a contractual and financial level for something that may not end up being relevant. 

When There Isn’t Any Document at All

For many businesses, especially those new to an agile approach to software development, the issue of finding the right balance of documentation can be a complicated task.

However, there is a difference between not having any documentation versus indecision. If the business is clear with their values, goals and expected outcomes on a strategic scale, developers are able to produce prototyped solutions quickly. This allows the business to acid test the investment against a consumer group.

When the business doesn’t have any documentation or a clear idea of what they’re looking for on a strategic level, it’s harder for developers to discern business rules required for the system. This often results in delays and a potentially flaky system because the business is unclear about what it wants, and therefore, developers cannot deliver a solution that is geared towards a specified problem. 

The issue here is not due to the lack of documentation, but rather the business is unable to communicate their needs and wants. This can be crippling to the software development process and pose a threat to delivery velocity despite being on the opposite spectrum for documentation.

This is because documentation not written by developers is more a tool to clearly capture the wants and needs of the business without dictating to developers what they should be doing. 

Balanced Approach with Living Documents

The idea of having living documents means that all parties involved in the software development process contribute to the externalization of knowledge. 

It is written by each group for a particular audience and is called a living document because of its activity. The initial documentation for the entire project creates an ideological scaffold for the software to fulfill. It is not prescriptive, nor is it overly descriptive. The living document aims to capture parts of knowledge that are not immediately obvious in the code. 

This means that for certain audiences, more documentation will be required than others, and is based on relevancy only. For example, the business analyst is only expected to capture required business rules for backend developers to translate. Backend developers are expected to document their translations for their consumers, such as API documentation for frontend developers. 

There is no single person or group that creates or maintains the process of documentation in isolation. When this happens, over-documentation in certain areas will often occur. 

The best approach to documentation is to distribute the workload among different groups and only document what is actually necessary. This will put less risk of falling into a waterfall method while maintaining clarity for the business and their developers. 

Co-authored by:

Dave Wesley ~ President, SRG
LinkedIn

Aphinya Dechalert ~ Marketing Communications, SRG
LinkedIn