Categories
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

Background

  • 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
$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
$50.00
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:
$33.33
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:
$33.33

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

Questions/Decisions

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

Summary

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.

4 replies on “Example of lightweight feature documentation 📃”

Hi Alister, great post!

It is an example of example mapping. Since you did not refer to it in this post, here is the link:
https://xebia.com/blog/example-mapping-steering-the-conversation/

What is your opinion on the Example Mapping technique?

I think that I spotted an error in scenarios/examples section:

Two artists with 50% each for a payment that can be rounded to ten cents – no rounding $100.30
artist 1: $50.15
artist 2: $50.30

artist 1: $50.15
artist 2: $50.30

I think that this scenario is artist1: 50.15 artist2: 50.15.

Regards, Karlo.

Thanks, that was a typo and I’ve fixed it.

Thanks for the link. It looks very similar. The main difference I think is we don’t use any post it notes – we do ours straight into Confluence or a Google Doc – also all our example are written in tabular form as I find it much easier to read and organise tubular data. It’s interesting they suggest not to worry about Gherkin!

Hi Alister,
I have a question … how to combine sample map meetings, tables and designs at the same time?

for example, when it comes to forms? Currently, we get used to having a design and from there writing too much flat information. However, I don’t know how to play with those tools to see tables and rules and maps instead of paragraphs and information distributed in a great word document.
and above all, that the developers read it hahaha

Unfortunately, this won’t work in companies with more than 10 employees… We cannot use this option since we will end up again with Ms Word files kept on a shared network folder, in SharePoint, in Confluence or any “away-from-code” collaboration solution.
It also defeats the original purpose, that of refactoring legacy code easier.
New employees won’t have time and the will to immediately read old documentation, but rather they will start messing with the code wrongfully thinking they can improve it right away, given the fact that they will be bringing fresh knowledge and energy in your company. A CI server, in turn, won’t bother running and failing your acceptance tests.

Leave a Reply

Your email address will not be published. Required fields are marked *