“Working software over comprehensive documentation” is the second value stated in the Agile Manifesto. The Manifesto’s signatories were fighting against the business and technical requirements documents synonymous with waterfall software development projects. They recognized these documents were a symptom of the failures and frustrations in many software development projects because they took too long to write, were too complex to consume, and were often outdated by the time development teams reviewed them.

The success and popularity of agile methodologies partially stem from how stakeholders and development teams collaborate. Instead of stakeholders writing lengthy requirement documents—often without a development team’s input—collaboration goes into continuous planning, user story writing, story estimating, sprint commitment, and other agile and scrum practices.  

Unfortunately, some people have taken this principle too far, suggesting that agile teams don’t need documentation or don’t have to create documentation.

There’s some rationale behind these sentiments, especially when stakeholders and product owners don’t trust their development teams and request detailed documentation as a substitute. Furthermore, during the first decade of agile’s growth, creating, maintaining, searching, and using knowledgebases was a subpar experience compared to using today’s tools that integrate with the technologists’ development platforms and workflow.

Why create and maintain documentation?

Knowledge management and technical documentation maintenance are critical today because businesses are developing more software than ever before while devops teams are releasing changes frequently. The expectation is that devops teams create APIs, integrate cloud-native applications with other systems, and enhance capabilities over time. If there are incidents, security issues, or other defects, stakeholders expect agile teams to fix and release changes easily.

No one wants a new decade of legacy systems and technical debt that development teams will struggle to maintain and improve. Expecting new developers to join software development projects and learn how a system functions without documentation is unrealistic.  

Copyright © 2021 IDG Communications, Inc.