Agile Software Dev

Example of lightweight feature documentation 📃

In response to my article about BDD in 2020 I saw this question on Twitter:

I thought it would be easier to write an answer here and provide an example.

I’m not keen on writing specifications in gherkin (Given/When/Then) as I think it’s too generic and frequently makes the feature specifications too verbose – and takes emphasis away from the critical parts.

Here’s a made-up example of some lightweight feature documentation that would be generated during the development process. The important thing to note is the actual documentation artifact generated isn’t as important as the collaborative process that is involved in generating it. This is often about asking the right questions and adding more examples until there’s nothing that is unclear.

The document isn’t a template – the actual documentation varies based on conversation, problem and context.

Example: Royalty Payment Splits


  • Royalties need to be paid in full on disbursement to artists.
  • A royalty payment can be made to an individual artist, or a group of artists.
  • When making payments to an individual artist they get 100% of royalties (no rounding)
  • When making payments to a group of artists this needs to be split by the percentage splits defined in the system which always add to 100%
  • When splitting a payment across a group of artists and it doesn’t split evenly into cents, the system currently randomly splits the cents between artists to balance out the rounding over time
  • This causes issues for both automated tests which need deterministic behaviour, and artists who are confused why they get slightly different amounts if their royalties are the same.

Scenarios / Examples

ScenarioRoyalties OwedCurrent Royalties Paid New Royalties PaidTesting
Single artist gets 100% of whole payments$100.00$100.00$100.00
Single artist gets 100% of payments including cents$66.67$66.67$66.67
Two artists with 50% each for a payment that can be split evenly $100.00artist 1: $50.00
artist 2: $50.00
Two artists with 50% each for a payment that can’t be split evenly$100.01$50.01 / $50.00 is randomly assigned to artist1/artist2artist 1 $50.01
artist 2
Two artists with 50% each for a payment that can be rounded to ten cents – no rounding$100.30artist 1: $50.15
artist 2: $50.15
artist 1: $50.15
artist 2: $50.15
Three artists with third splits can’t be split$100.00amounts of $33.33, $33.33 and $33.34 randomly assigned to group members artist 1: $33.34
artist 2: $33.33
artist 3:
Three artists with third splits can’t be split – more than a single cent difference$100.00amounts of $33.33, $33.34 and $33.34 randomly assigned to group membersartist 1: $33.34
artist 2: $33.34
artist 3:

Business Rules

  1. Royalties need to be paid in full on disbursement to artists.
  2. A single artist gets a whole payment.
  3. When payments can be split evenly to a group of artists (to the cent) they are split that way.
  4. When payments can’t be split evenly to a group of artists, the payments are split into an even split and the remaining cents are distributed to the members in whole cents.
  5. The first member in the group – based on earliest date/time added to group – gets the higher amount, followed by the second, third etc. based on earliest date/time added.
  6. Payments aren’t rounded to ten cents or five cent amounts, only whole cents


QuestionDecisionMade By
Do we want to round to five or ten cent distributions?No, we’ll always round to the centProduct Owner via Slack #
How do we distribute based on membership of group?We’ll use the date time added to the group (first gets most)Team during kick off meeting


I think trying to force the above information into gherkin (Given/When/Then) statements would make it less readable and provides no added benefit – whilst Given/When/Then encourages consistency sometimes you just need structured thought that is most relevant to your context. The above document isn’t a template – it varies for the problems we’re trying to solve.

Agile Software Dev

BDD in 2020

It’s 2020: can we officially declare Behaviour Driven Development (BDD) dead?

How did we get here?

“There is no trap so deadly as the trap you set for yourself.”

Raymond Chandler, Long Goodbye

BDD’s lure was the promised land of collaboration between business and technology defining expected behaviour as executable specifications (automated tests). These automated tests defined our software development processes: outside-in software development, behaviour driven development, acceptance driven test development and specifications by example.

BDD’s trap was a bunch of Cucumber specifications written after the fact that create another layer to automate tests in a browser, hidden away in source code which are seldom, if ever, seen by the business, and either too comprehensive, flaky and expensive, or narrowly focused but lacking in enough detail for a complete executable specification of a system.

Sure BDD tests can drive things besides the browser, but the overhead and complexity of maintaining these outweighs the benefits they serve, especially when there is still a need for more expensive integration/e2e tests anyway.

So what actually works in 2020?

I’ve found this process seems to work really well for modern software development in 2020:

  1. Every new piece of work has a kick-off discussion with the product owner, the tester and the developer(s)
  2. The tester usually facilitates this meeting and aims to produce written lightweight documentation during the discussion containing the following information: background info, scenarios, business rules, examples (edge cases), questions and decisions.
  3. This documentation is enough for development work to begin, and the tester to plan how they’ll test it.
  4. The documentation is updated as work progresses: questions arise and decisions are made (and documented).
  5. The developer(s) is/are responsible for making sure there is automated test coverage for these business rules at the cheapest level of testing, these are typically automated unit and/or automated integration tests. These aren’t written in business readable language, they’re test code alongside production code.
  6. The developer also needs to ensure any existing automated end-to-end (e2e) tests are updated for the work that is happening – CI builds highlight these impacts/failures.
  7. When the feature, or a working part of the feature, is ready for testing the developer and tester do a quick handover/walkthrough making sure what was done is what was discussed.
  8. The tester uses the lightweight documentation as a basis for their testing, but adds extra rigour in testing edge cases/unknowns, other impacted areas, different browsers, performance, and devices and anything else they think could be risky.
  9. Bugs that are found and determined by the product owner to be crucial are fixed immediately, some bugs become “fast follows” which are the next thing to ship. Some bugs aren’t fixed.
  10. The tester gives a walkthrough to the product owner and sometimes UX designer to make sure what’s been done is acceptable – if the feature is new/risky it’s launched to a subset of customers and can be disabled at a flick of a toggle.
  11. When an entirely new feature is added to the system and it’s important enough to warrant an (expensive) automated e2e test – the tester works on adding that in amongst their other work. This isn’t a blocker to release and provides a safety blanket for future changes. This isn’t a comprehensive specification of the system – it’s an e2e automated test that covers a business critical flow over multiple moving parts and again doesn’t need to be business readable.
  12. The specifications/documentation lives on in a wiki page and can be referred back to when testing future changes to this feature, or when support tickets or bugs are found in production.

BDD isn’t working for us, what can I do now?

  1. Make sure you commit to having kick-offs and encourage robust discussion creating lightweight documentation as you go – remove uncertainty and create clarity by making and documenting questions and decisions.
  2. Keep your lightweight specifications up to date as you go – don’t worry about making them executable – let people write automated tests in the way that is the most efficient for them.
  3. Only use automated e2e tests to cover key user flows in the most efficient way – don’t use these to create/maintain comprehensive living documentation.

Also See:

Ask Me Anything ATDD Business Driven Cucumber Specflow Specification by Example

AMA: adopting a TDD/BDD approach

João Monteiro asks…

I recently joined a small company where I am the only QA and the test automation suite was already written in a given/when/then style but rarely (if not at all) gets read by the rest of the team (product or developers). Any tips on how to mentor the team to adopt a BDD approach? Do you recommend any tools / framework to share the features in a centralised place easily accessible by the rest of the team an not just on the tests repository?

Automated Acceptance Testing Automated Testing Specflow

You probably don’t need a specification framework

I think plain language specification frameworks like SpecFlow and Cucumber are great, but have a lot of overhead and are way overused.

If you don’t have non-technical folk collaborating with you on your specifications, try writing plain automated tests instead. This means using plain NUnit/MSTest over SpecFlow in C# or minitest over Cucumber in Ruby. You’ll avoid the overhead of maintaining a plain language specification framework and be able to focus on developing a great set of tests instead.

It’s easier than you think to add a plain language specification layer to a set of well structured plain tests. So only add the specification layer when you need it, because chances are you ain’t gonna.

Automated Acceptance Testing Automated Testing

Don’t bury your hooks

A slightly technical post here.

If you’re using a BDD framework such as Specflow or JBehave, can I please ask that you don’t bury your hooks. These frameworks provide hooks, or events, you can use to repeat certain things. An example in Specflow is:

public static void GoToHomePage()

You can put these hooks in any steps class, but please, put them in one place, all together, preferably in a class/file named hooks or the like.

I recently came across a code base where these hooks where spread across lots of different steps files, which makes it very confusing and hard to debug as you don’t know where all this code is being called from when you’re running your tests.