Skip to main content

The Agile Manifesto is built on four values. One of the values is “Working software over comprehensive documentation”. This means, working software should be valued over comprehensive documentation. Unfortunately, this is one of the misinterpreted values or to phrase it from one of the Scrum Alliance founders Mike Cohn, “one of the most misused parts of the Manifesto”. It is often interpreted as ”skip all documentation”.

Working in an agile environment, with the need to adapt to changing needs and requirements, the quality over the quantity of the documentation and its process is more important than ever. In this article, we want to emphasize documentation tips and key points that we think are important for Business Analysts working in an Agile environment.


#1: Use a Template

Create a simple template with a couple of headings that will be used as a guide while creating a document. This will be time saving; you will not spend time staring at a blank page and thinking on what to write. It will also make sure you do not skip important points. Templates also provide consistency and structure. The readers (the team or the stakeholders) will know what will come next.

Keep in mind that there is not only one template that will suit every team in the organisation.  There can be different needs depending on the stakeholders, technology etc. But yet, there are also some standart topics that can be included in almost all document templates, such as “Overview” with background information about the project.


#2: Write User Story with Acceptance Criteria

The Agile Manifesto value “Working software over comprehensive documentation” was coined when most of the projects were done in a document driven Waterfall model with maybe hundreds of pages of documentation. While working in an agile environment, the quality of the documentation is more important than the quantity. User stories are a great way to express requirements in a qualitative way.

“A user story is an informal, general explanation of a software feature written from the perspective of the end user.” Most common template of a user story is as below:

As a [persona],
I want to [some goal] So that  [some goal]

As a Business Analyst, spend some extra time writing user stories. It will help you to understand the requirements better.  Ask yourself; Who will need this (As a…), what is the intent of the task, what is desired to be achieved (I want to..) and what are the benefits/goal/vision of this (so that..).

The user story has to be so clear that “After reading a user story, the team knows why they are building, what they are building, and what value it creates.“

Make sure to write Acceptance Criteria to confirm the User Story is complete. Acceptance Criteria can be used to even cover non-functional requirements. Acceptance Criteria will also aid the team in understanding a user story and also reduce the time spent on writing test cases since it describes the system’s behavior upfront. A good way to write Acceptance Criteria is in Given/When/Then format:

  • Given [context]
  • When [action]
  • Then [result]


#3: Living Documentation – Edit and Update as Needed

In an Agile environment, you have to be open to changes. Make sure your documents are always up to date. Always update important points when you get new information. Do not think of the documentation as finished just because you had a production release. You can edit and update the documentation also after production release.

Use online documentation so that everyone in the team can easily access it. Do not leave important decisions in e-mail or chat. Update your documentation.

By keeping a good and manageable documentation structure, focus on quality instead of quantity, keeping your documents up to date, then your documentation will support agility and you will not just be a Business Analyst working in an “Agile” environment, you will be agile.


Ayla Erhan

Business Analyst Consultant at Coca-Cola CCI

Content Writer at BA-WORKS