Tribridge Connections

A Technology, Cloud Solutions & Industry Expertise Blog


Agile Misconception #3: “Documentation is not allowed.”

Published: May 07, 2014

In my last Tribridge blog post about Agile Software Development, I talked about the popular misconception that gathering requirements is not Agile. Today I will address arguably the most pervasive myth about Agile, which is the belief that with Agile projects, no documentation should be produced. In fact, I've seen Agile teams refuse to produce documentation because they claimed that Agile didn't allow it. Of course, this simply is not true. Agile teams can produce as much documentation as they want. The key distinction is that documentation should always have clear value to the customer, and only include necessary information.

What's Wrong with Waterfall Documentation?

In short, the biggest problem with documentation on Waterfall projects is waste. Documentation is often produced because “that's how we've always done things” or because “management requires it”. If these reasons are used as justification for spending hours writing documents, then there is a good chance the documents themselves are not producing value for the customer and that value is not being measured. Unnecessary documentation can create huge amounts of waste – wasted time creating documents, wasted time reading documents, and wasted time changing documents that become out-of-date. The goal with any Agile project is to minimize waste and focus on tasks and activities that produce continuous value to the customer. Just like software developers should focus on creating valuable code, and avoid creating unnecessary code, teams should also strive to only produce valuable and necessary documentation.

Documents Should Not Replace Face to Face Communication

There's nothing inherently wrong with documentation, no matter what methodology that is used. However, when detailed specification documents are created too early (also known as “Big Up-Front Design”), it is common for both the customer and the development team to assume that all design is done and additional communication is not required. This assumption is what causes many software projects to break down and fail.

Constant communication is required, not only because specifications may change over time, but also because specifications are not perfect and people usually interpret them differently from one another. A Business Analyst may create a specification document with one idea in mind, but a Software Developer may imagine something different when reading the document. However, daily communication and collaboration is still required, even when a specification document exists. Good specification documents are important, even in Agile projects, to help clarify ideas and decisions that are made. But these documents should serve to enhance, not replace, daily face-to-face communication.

How Agile Teams Should Produce Documentation

There are many types of documents that software teams produce: project charters, requirement lists, design specifications, technical process flows, user manuals, etc. As a rule, Agile teams should produce lightweight, high-level documents during early stages of the projects. Then they should fill in more details as time goes by and as the team learns more about how to deliver value. However, no matter what type of documentation is created, it should be delivered to the customer at the end of every iteration. Every document is a deliverable, just like working software is a deliverable, which can be reviewed by and with the customer. The customer can provide immediate feedback on the documentation so the team knows if it is valuable or not. Based on that feedback, the team can make adjustments to the documentation with each iteration. By the end of the project, the team will have produced documentation that they know has high value to the customer.

Learn More

Want to learn more about how Agile can help companies align their business and technical teams to remain flexible and ready to conquer any challenge that comes their way? View our recent webinar: Aligning your Business and Software Development Teams with Agile.

Share Your Thoughts With Us

Load more comments
Thank you for the comment! Your comment must be approved first