Working Software vs. Comprehensive Documentation — BDD Makes the Save

6 min readJun 3, 2021


By Serge Gorbachev, Director General at Rosberry

In 2001, when Agile Manifesto was created, the world of software development was a little different. Everyone was tired of massive and long projects, which were really hard to manage. Too much effort and time was spent on making solid technical requirements, and more effort was required to implement them. There was a lack of transparency, no feeling of dynamics, teams were burning out. In such circumstances, or better say due to such circumstances the Agile in software development was born.

Scrum, as a full-fledged example of Agile, came to help desperate teams, which were just about to fail, and that coming out was like a miracle. If we take what’s written in Scrum by Jeff Sutherland for granted, Scrum improved the efficiency of teams by 400%. No wonder, if you are at the bottom and a scrum coach helps you organise your team and processes, then you really can boost 4 times. But obviously you have to sacrifice something to gain that, something that had taken time and energy but didn’t give the co-valuable result back. As we say: “If you need to buy something needless, sell something needless first”. Well, that’s exactly what happens in Agile, check out its 4 values:

Individuals and interactions over processes and tools.
Working software over comprehensive documentation.
Customer collaboration over contract negotiation.
Responding to change over following a plan.

Many, who read the second value, understand it this way: “If we can make working software, then we don’t need to make/support comprehensive documentation”. Fortunately for mobile development companies, where a project lifecycle is relatively short, they really can do it without comprehensive documentation. If a project lasts less than 6 months, everyone in the team including a client can keep all the context in mind and make a product which a client can be happy with. But it’s better to quit right away, otherwise you’ll be in pain doing things like: major updates, onboarding new developers, guaranteeing high quality of this product, etc. More lucky are those, who fit into their estimates of fixed-price projects, or put their failures on their client’s shoulders.

But we are interested in those companies, which do a fair business, which care about the quality of the product, which strive for long-term relationship and big projects. Such companies can use ATDD (acceptance test-driven development) in order to fix this issue with documentation. Either they got there from TDD (test-driven development), or BDD (behaviour-driven development) or they have just started ATDD and it worked.

Please, don’t treat the word “behaviour” in regards to a human being only. Behaviour here has a more common meaning, which describes the behaviour of the system as a whole, which can be triggered by an action or an event.

ATDD does not compete with a solid “comprehensive documentation”, which is usually created by experienced analysts and architects. Comprehensive documentation — it’s like a katana sword by a skilful sword master. It’s a hard to get, expensive, single purpose thing, which only specially trained people can use. While ATDD — it’s like a Swiss army knife, which is cheap, multi purpose and even a teenager can use it. Which of these two things is more useful — depends on the problem you are about to solve, however our life experience can tell that a Swiss army knife helps us way more often.

Due to ATDD we create the context of a project, which is easy to understand for everyone involved: a client, managers, developers, QA. Usually acceptance tests have the following form:

Given (setup)
A specified state of a system

When (trigger)
An action or even occurs

Then (verification)
The state of a system has changed or an outcome has been produced

and they perfectly complement user stories, showing on real examples the functionality of the system. Here’s a sample of their combination:

Title: Returns and exchanges go to inventory.

As a store owner, I want to add items back to inventory when they are returned or exchanged, so that I can track inventory.

Scenario 1: Items returned for refund should be added to inventory.
Given that a customer previously bought a black sweater from me
and I have three black sweaters in inventory,
when they return the black sweater for a refund,
then I should have four black sweaters in inventory.

Scenario 2: Exchanged items should be returned to inventory.
Given that a customer previously bought a blue garment from me
and I have two blue garments in inventory
and three black garments in inventory,
when they exchange the blue garment for a black garment,
then I should have three blue garments in inventory
and two black garments in inventory.

A simple and easy to read language helps in avoiding vague descriptions and any further duality in understanding.

Usually, in mobile development outsourcing a client brings some sketches and so-called “technical requirements”. For some dashing companies that’s more than enough to kickstart this project. But in fact this information is not sufficient to give accurate estimate and get client’s expectations and team’s plans in sync. Design is usually not complete, and technical requirements are just a two-page document at best. However, if ATDD joins the game, then many pitfalls get uncovered: potential server errors, internet connection issues, empty fields, confirmation dialogues, dependencies of one element on another, and many more…

Perhaps the ace of trumps by ATDD is that with a proper attention to scenarios syntax, they can be automated.

Thus scenarios help:

  • a client and a team to get on the same page about the requirements and functionality of a project;
  • a team to better understand the project and give accurate estimate of implementation;
  • a team not to lose a tiny detail, which is important for a client or a project;
  • a QA team with manual functional and regression testing;
  • everyone, when scenarios are automated, because it saves a lot of time and money and gives a certainty in quality of the result;
  • a client, who gets not only the source code, but a source code with live documentation.

Why “live documentation”? Because it’s live (if you keep it alive of course) and it’s changing along with the project. You have to keep documentation up to date at all times, only then it has a value. Fortunately the language of documentation is not complex and adding changes on the fly is easy.

However, behind this simplicity there’s a long transformation process inside the developer’s team.

  1. It all starts with the understanding of TDD philosophy: in order to make something right, you shouldn’t start making it ASAP, but think of how you will make sure you did right things.
  2. It carries on with the understanding of value and importance of BDD as a process of communication of the entire team. Without specification by example, everyone in the team can get the requirement in their own way.
  3. And finally, it ends with understanding that without written acceptance criteria by ATDD it’s not possible to get the result accepted and make sure it is a quality one.

But we know that understanding is not enough. Practice that’s what matters. Writing good quality scenarios is not fast, and is quite emotionally intense activity. It feels like you are using those parts of your brain, which you have never used before, when you write scenarios. At first it’s painful, but gradually it starts working out and then it all goes like clockwork giving you inspiration and pleasure.

Gradually the team accepts the idea of BDD and starts suggesting some reasonable improvements:

  • making a glossary for scenarios;
  • making template scenarios, widely spread among various projects;
  • cross-platform tools for automation;
  • education sessions for those teammates, who have never created scenarios before.

This is the best confirmation that the philosophy of BDD has been successfully grafted and is living inside the team.

My story with BDD started with the book BDD In Action by John Fergusson Smart. Now, three years later, we have still been doing ATDD, and it’s hard to imagine how we can estimate new project without scenarios, how we can develop it without scenarios, and then how we can test it and guarantee a quality to our client. It seems that ATDD as an approach has completely taken that space, which earlier was taken by “comprehensive documentation”, but there was no room for it in Agile.

I don’t insist on ATDD being the only right way — each and every company should choose its own way. I’m only saying that at some point we tried this approach, we liked it and now we can’t live without it. It’s really easy to learn, but hard to master.




Rosberry is a mobile app design and development company based out of Thailand. We design, build, test, deploy and support apps at scale.