Example of lightweight feature documentation ๐Ÿ“ƒ

https://alisterbscott.com/2020/05/29/example-of-lightweight-feature-documentation/

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.

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 PaidNew 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.15artist 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 membersartist 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.