Often, I have heard Software Architects, Engineering Managers, and Engineers say that self-documented code is the only documentation needed. This thought is an oversight. Depending on the architectural and development processes employed, or the lack thereof, one often documents accordingly. Furthermore, I have found a lack of awareness about the benefits of documenting architectures and solutions. This lack of awareness results in a misperception that spending time on documentation is a waste of time.

How is this an oversight and why does it cause a misperception? To answer these questions, let’s talk about who the audience is and what benefits documentation provides to the audience.

For Software and Enterprise Architects, the audience consists of stakeholders such as customers, Executives, fellow Architects, Product Managers, Project Managers, Engineering Managers, Software Engineering teams, design teams, and Quality Assurance teams. Architectural documentation is necessary for architects to communicate with stakeholders and is a necessary part of architecture methods.  These methods include but are not limited to the Architecture Development Method (ADM) and the Architecture Trade-off Analysis Method (ATAM). Other examples of architectural documentation include documentation for architecture deliverables, approaches, snapshots, and plans. Without documentation, the stakeholders would be without the required information, deliverables would be incomplete, and it would be more difficult to evangelize about architectures.

For Software Engineers, the audience typically includes the customers, Software and Enterprise Architects, Engineering Managers, Product Managers, Project Managers, fellow Software Engineers, and Quality Assurance teams. Software engineers use visual diagrams, code docs, and other documentation to enable others to understand solution functionality without having to read the code. Additionally, when solution authors go back to check the solution(s), providing documentation is useful by providing context, high to low-level details, and answers to questions starting with where, when, how, and why. Finally, documentation can increase the ease of recognition with various contexts, containers, components, and code. Without documentation, the audience will not receive vital information, fellow Software Engineers will need to check the code in-depth to learn/re-learn it, and recognizability will suffer.

The phrase, self-documented code is the only documentation needed, is an oversight because the benefits of providing documentation are often unknown.  As a result, taking time on documentation is often perceived as a waste of time and not considered a priority.