The Positive Influence BAs Have in the Quality of Documentation in Agile Projects

Author: Adriana Beal

As you read the title of this article, you may be thinking, “Doesn’t agile methodologies emphasize verbal rather than written communication? Is there any value in even talking about documentation in this type of project?”

The answer is yes to both questions. Agile developers may require very little written documentation to do their work, but documenting has many purposes beyond understanding what needs to be built. The need to produce documentation (written or in other formats, such as video recordings) may exist throughout the life of an agile project in different circumstances, including:

  • When an iteration is about to start, and the programmers need to be reminded of implementation decisions and hard-to-remember requirements (such as complex business rules that apply to a user story);
  • When the organization is preparing to hand off the project to another team that will maintain the product, and readable code plus automated test cases are deemed insufficient to explain system behavior or to clarify the reasons behind certain implementation choices that may affect future enhancements;
  • When end users will start to use a new product or feature, and need help understanding how to operate the software;
  • When regulation and compliance issues require a permanent record of implemented system behavior.

Many people interpret “documentation” strictly as formally written documents, but, as pointed out in the book The Art of Agile Development,

If you think of documents as communication mechanisms rather than simply printed paper, you’ll see that there are a wide variety of alternatives for documentation. Different media have different strengths. Face-to-face conversations are very high bandwidth but can’t be referenced later, whereas written documents are very low bandwidth (and easily misunderstood) but can be referred to again and again. Alistair Cockburn suggests an intriguing alternative to written documents for handoff documentation: rather than creating a design overview, use a video camera to record a whiteboard conversation between an eloquent team member and a programmer who doesn’t understand the system. Accompany the video with a table of contents that provides timestamps for each portion of the conversation.

Expecting customers to write comprehensive acceptance test documents, or programmers to produce effective user manuals, is unrealistic in most organizations: stakeholders and development teams rarely have the time and the combination of competencies necessary to produce such deliverables with the velocity and quality that is needed for the project to succeed. Having a skilled business analyst responsible for creating the necessary documentation minimizes the risk that such deliverables are not ready at the time they are needed, or lack the level of detail and quality required to achieve project goals.

Agile places a greater emphasis on working code over comprehensive documentation, but that doesn’t mean that documentation goes away–only that it is reassessed according to the value it provides. Even though documents are not supposed to replace getting the right people in a room to work things out together, the right piece of documentation may be crucial to keep the focus of the team on the rapid delivery of business value.

Well developed business analysts can help agile teams in all aspects of communication, from selecting the documentation methods and formats that are most appropriate for the project, to producing quality documents and ensuring that the pieces of document are ready at the points of the project when they are needed.

>> Learn More About Agile Requirements

These articles address the types of requirements most commonly found on agile projects:


Free Training - Quick Start to Success

(Stop the frustration and earn the respect
you deserve as a business analyst.)

Click here to learn more

By signing up, you agree to our Privacy Policy.


  1. Marta Dabrowska says

    One of my favourite aspects of Agile is the concept of ‘just-in-time-documentation’. As my team is working on contractual basis, the acceptance scenarios and features documentation are project deliverables as well and we always need to look for balance between developing and documenting. We go for lightweight documentation that both developers and customers agree upon. The documentation is accessible and reviewed by everybody on the team and we never consider it as set in stone. So far our approach has been successful and makes my life and job (transitioning from QA to BA role) a lot easier.

  2. Brandon — how timely is your comment! Today Bridging the Gap published another article I wrote about this subject,

    The purpose of this new 2-part article is to address this tendency to “shy away” from documentation caused exactly by the reasons you mention. However, instead of choosing between two opposing models: a huge effort trying to keep all documentation always up-to-date, or giving up entirely in having useful documents, BAs should start using integrative thinking to “constructively face the tensions of opposing models, and instead of choosing one at the expense of the other, generating a creative resolution of the tension in the form of a new model that contains elements of the both models, but is superior to each”. Thanks for writing, and I hope you will leave your insights at the new articles as well.

  3. My experience has been many shy away from documentation for one of two reasons: 1) it’s perceived as difficult to create or maintain so it’s considered “a lot of work,” or 2) many feel as if once you create the document it is written in stone. There is also a stigma documentation means sitting down with Word or Excel and pounding out a ton of detail. You provide some excellent examples on different types of documentation and make excellent points. Thank you!

  4. Thank you, Laura, and Brian, for adding your views!

    Laura, your story is a great example of how documentation can provide value throughout the lifecycle of a system, particularly when complex behavior and business rules need to evolve with time.

    Brian, I share your view that in time more agile teams will start to recognize the value that the right documentation adds to projects, as they go through experiences like the one described by Laura.

  5. Brian Haas says

    Your statement of “but that doesn’t mean that documentation goes away–only that it is reassessed according to the value it provides” is spot on. Too often, teams adopt agile and under that banner, cease documentation. This certainly gets the team to coding quicker, but at the expense of the communications mechanism that documentation provides. (As your book excerpt notes). In time, I think many agile teams will do exactly as you suggest… reassess the importance, value, and targeted depth of documentation as a necessary communications mechanism of agile software projects.

  6. Adriana,

    Another great post (as always!). I’ve got a story to share! On my first agile project I was helping the business make a transition from a RUP process to an agile one. They had a large body of use cases that documented most of the business rules embedded in the system. (We could argue about whether or not this was the best way to document this, but that’s another piece of the story.)

    In this agile project, we were building a new system that integrated with the existing system as well as updating the existing system with revised logic. As part of the documentation for the project, I updated all of the existing use cases with the new rules. The stakeholders heavily rely on these use cases when modifying the system going forward, so it was a rather high value set of deliverables to maintain.

    We also used pieces of this documentation as attachments to user stories. A few integration points were highly complex and involved upwards of 20-30 rule changes to get right. No one could keep all the changes straight in their head, regardless of relying on verbal communication alone to communicate them. So oftentimes, we attached these documents to the stories to be the reminders of all the rules for the developers.


Before you go, would you like to receive our absolutely FREE workshop?

(No formal experience required.)


Quick Start to Success
as a Business Analyst

By signing up, you agree to our Privacy Policy.