As Architects and Developers, we have all been in projects writing high-level to low-level design documents. Design documents are a common artifact in software development projects, but their usefulness and effectiveness in an Agile organization have been the subject of debate among IT teams. The main intention of the design documents is to ensure that all stakeholders understand the project goals, technical blueprint, and requirements at a granular level. But, limited audiences are reading this document, and very seldom do these documents get updated. Hence, these documents tend to become cumbersome, time-consuming, and ineffective.
The Case for writing Technical Design Documents
In a waterfall project software lifecycle moves from one stage to another, and writing design documents made a lot of sense as these were a deliverable and inputs to the next stage. Also, it served as a reference for various teams throughout the project lifecycle without many changes to the document. Additionally, in large projects where the development team expanded rapidly in different stages, design documents became helpful for onboarding new team members.
However, developers still complained if the document became too long or technical for business stakeholders. Additionally, in a fast-paced project where requirements changed abruptly, design documents quickly became out-of-date or irrelevant as the project progressed, rendering them ineffective as a reference.
The Case for Minimal Documentation
In recent years, with several organizations adopting the Agile work model, there has been a growing trend toward minimal documentation. This approach typically emphasizes lightweight and flexible documentation and more on communication and collaboration among team members. Facilitation happens via regular meetings, syncs, retrospectives, tech guilds, stand-ups, and other forms of communication. Different Agile teams adopt different strategies:-
One of the minimal documentation approaches is to use lightweight documentation tools, such as Wiki or shared Google Docs, to document project goals, requirements, design, Architecture artifacts, decisions, diagrammatic representation of solutions, etc.
Some teams that involve business teams closely follow a BDD/TDD approach and want that as a starting reference for any requirement or even design-specific decision. The development teams also follow a strategic approach towards committing code and documenting every release into production.
Development teams that hate to write documentation can use code documentation like Doxygen, Javadocs, etc or template-based tools like Markdown, Asciidoc, etc that generate documentation based on source code annotations, structures, or comments using automatic scripts.
Conclusion
Most development teams in today's Agile Organizations hate design documents as they are time-consuming and have maintenance overhead. They can slow down the development process leading to Analysis Paralysis. Also, many tools and techniques are available to automate the creation of diagrammatic representations and technical blueprints in the development process.