Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Towards a canonical definition of BDD (WIP) #376

Open
wants to merge 21 commits into
base: master
from

Conversation

@mattwynne
Copy link
Member

commented Sep 3, 2019

In my shiny new job as a BDD Advocate at SmartBear, I have plenty of time to focus on helping the world learn the delights of BDD.

It's always bothered me that there was no single place you could point someone to help them understand what BDD is. I'm aiming to build that here on Cucumber's docs.

Together with the help of @sebrose, I've done my best to write a brief summary of the key ideas as we tend to teach them these days. My plan is to build out from here and write more pages that go into more depth, but I'd like some feedback on this introductory page first. Please ignore the links at the bottom to sub-pages, I'm ignoring those for now.

I'd like to make this into a page that all of us in the community are happy with, and I will be interested to hear differences of opinion - as always, the places we see things differently as the places we can learn 馃榿

You can see a preview here.

@mattwynne mattwynne requested review from tooky, aslakhellesoy and sebrose Sep 3, 2019

@mattwynne mattwynne self-assigned this Sep 3, 2019

@mattwynne mattwynne requested review from lunivore, cukebot and everzet Sep 3, 2019

@mattwynne

This comment has been minimized.

Copy link
Member Author

commented Sep 3, 2019

@tastapod I would love your thoughts on this.

@mattwynne

This comment has been minimized.

Copy link
Member Author

commented Sep 3, 2019

@richardlawrence I would love your feedback on this too.

@mattwynne mattwynne requested a review from ryan-mars Sep 3, 2019

@mattwynne

This comment has been minimized.

Copy link
Member Author

commented Sep 3, 2019

@ciaranmcnulty any thoughts on this?

@mattwynne

This comment has been minimized.

Copy link
Member Author

commented Sep 4, 2019

@gojko I'd love your feedback on this.

@gojko

This comment has been minimized.

Copy link

commented Sep 4, 2019

after a brief glance (I'll send more info soon), I think you're missing something around building a shared understanding across roles, and something around speed and how it fits into short iterations. Playing the devil's advocate here (I know this is not what you intended, but put on a newbie hat and forget the context), just read the three bullet points on the intro section of that page:

- Making a deliberate effort to avoid accidental discovery of business requirements late in the process.
- Eliminating defects and rework to achieve a confident, sustainable pace.
- Producing system documentation that is current, accurate and easy to understand.

All of this holds true as the intent of waterfall analysis and producing voluminous documentation upfront. I think the intro should clearly talk about what's unique about BDD here, which is collaboration across roles and speed.

I think you're also missing a major part of what comes after automation. in the book I called those two sections validating frequently and evolving a documentation system - so kind of plugging it into a frequent feedback loop and then refactoring both the docs and the automation as knowledge evolves. that is a major difference between this approach and letting the testing specialist team die with their obsolete tests in many large orgs.

@lunivore

This comment has been minimized.

Copy link

commented Sep 5, 2019

I prefer Gojko's "Specification" to the word "Formulation", which just means shaping or creating a stricture; that's a thing that happens all the way through.

@mattwynne

This comment has been minimized.

Copy link
Member Author

commented Sep 5, 2019

@gojko thanks. I totally agree about the speed thing especially. I find people often seem to miss this idea about small pieces and flow, perhaps because those of us with the curse of knowledge take it for granted so much we forget to point it out. So I'll see about bumping that point up from the "principles" into that main intro pitch. Same with the collaboration stuff.

Point taken about the ongoing "habitation" of the symbiotic code-and-living-documentation system, I'm going to play with how to communicate that.

@lunivore thanks, I think I agree with you about "Specification" vs "Formulation". What do you think about "Automation"?

@mattwynne mattwynne requested a review from gasparnagy Sep 5, 2019

mattwynne added 4 commits Sep 5, 2019
Responding to Gojko and Liz's feedback
I've added the practice of "habitation" and renamed "formulation" to
"specification".
@lunivore

This comment has been minimized.

Copy link

commented Sep 5, 2019

I'm OK with "Automation" though I tend to use "Test" as the third thing, since I'm doing BDD with non-software teams too (non-automated examples can also be used to test things!) But worth mentioning automation there even if it isn't in the title.

Also for the first one, since discovery is what happens but not what you actually do, may I suggest "Exploration"? That's the act of deliberately discovering things (as opposed to accidentally doing so).

@mattwynne

This comment has been minimized.

Copy link
Member Author

commented Sep 5, 2019

@gojko I may have mis-represented what you meant by "validating frequently" and "evolving a documentation system" (I don't have your book to hand today) but I've tried to represent them as a fourth, emergent practice of "Habitatition". Your thoughts appreciated.

@mattwynne

This comment has been minimized.

Copy link
Member Author

commented Sep 5, 2019

re "Exploration" @lunivore let's try it!

@mattwynne

This comment has been minimized.

Copy link
Member Author

commented Sep 5, 2019

@lunivore re "Automation" or "Test" my worry is that neither of those words conveys to (software) people that TDD is what we intend for them to do here. Does that concern you?

@mattwynne

This comment has been minimized.

Copy link
Member Author

commented Sep 5, 2019

Odd. The Netlify preview seems to have stopped working properly. The preview of the latest commit is here.

@mattwynne

This comment has been minimized.

Copy link
Member Author

commented Sep 5, 2019

@tomstuart 馃憢

@gasparnagy

This comment has been minimized.

Copy link
Member

commented Sep 5, 2019

I am generally fine with the structure, but I will read it through more in detail.

Finding the right keywords is always hard. We were thinking about this quite much with @sebrose when we called the three steps as discovery, formulation and automation in our book and we have used these terms pretty successfully to teach many people since them. As I have mentioned already once when we wanted to rename "scenario" in Gherkin, I think the point is not which English word will exactly describe what we do, because there will be no single English word that can describe such a sophisticated activity, but whether we can define the context where those words get their clear meaning. The discovery, formulation, automation trio has already some sort of community acceptance (I hear people talking about BDD using these terms), so we should consider whether the arguments of renaming are strong enough to destroy this.

From this perspective, for me "Exploration" is not much more precise then "Discovery", just to see the same thing from different angles. In our book we described this as "Explore and discover details through examples".

On the "specification" vs. "formulation", we were trying to use a word that is not that much overused. Specification has a lot of attached meaning and typically totally different than what we do there. It would be very confusing to teach people about the "BDD specifiaction" which is not the kind of "specification" that we would like to drive you away from. We were also considering "documentation" for this activity, but dropped in favor of formulation because of the same reason. Formulation means by Merrian-Webster: "to put into a systematized statement or expression", that we have found pretty much describing what we do there.

@tomstuart

This comment has been minimized.

Copy link

commented Sep 5, 2019

馃憢

Thank you for writing this, Matt! It鈥檚 really helpful.

You won鈥檛 be surprised to hear that I鈥檓 not very interested in the correct choice of Billable Nouns, so naturally I don鈥檛 believe you should be either 鈥 it鈥檚 best to use the words normal people would use. For example: if someone asked you in the pub what 鈥渆xploration鈥 actually means, what would you say? Does it mean 鈥渇inding out what everyone wants鈥, for example? You could just write that instead.

I also think it鈥檚 sensible to focus on software (i.e. automated testing) for the sake of clarity. You shouldn鈥檛 be coy about Gherkin being the 鈥渕edium that can be read by both humans and computers鈥, because that鈥檚 useful and actionable information. I think 鈥渄ocument those examples in a way that can be automated鈥 is confusing for people who don鈥檛 already understand what you鈥檙e describing; what is it about the examples that will be automated?

I really like the 鈥渇our practices鈥 section because it gets very close to answering the single most important question, which is 鈥渨hat should I actually do if I want to try BDD?鈥. There isn鈥檛 yet quite enough there to straightforwardly answer that, but you say you鈥檙e going to get into more concrete detail later, so as an overview it works well.

Overall, a great step forward! 馃憦

@mattwynne

This comment has been minimized.

Copy link
Member Author

commented Sep 6, 2019

Thanks for your input @gasparnagy and @tomstuart.

Tom, while I take your point about the ROI of fiddling around with words, what's important to me here is that this is a definition we can all live with and would want to point people to. So I'm more bothered about consensus and buy-in than wordsmithing. I'm definitely going to apply the "words normal people would use" filter in my next iteration - I love the idea thanks 馃憤

Back to those labels, I would like to try and settle on one-word names for the four practices (if we can agree on the four conceptually!) @gasparnagy it sounds to me like you have put a lot of thought into this already, and you make a really good case. I guess it's over to @lunivore - can you live with those terms from Seb and Gaspar's book? Maybe not perfect but good enough?

@richardlawrence

This comment has been minimized.

Copy link

commented Sep 6, 2019

I like how this is coming together, and I agree with most of the feedback so far. One big thing jumps out at me in the latest version...

In the "four practices" session, you mention iterative at the top and suggest it in the picture. But then, as I read the descriptions of each from a beginner's perspective, thinking about common misunderstandings I see in my clients, I get the sense that all the examples for a story are identified and specified in a large batch and then implemented one at a time.

In practice, I see good teams exploring examples a bit, then taking one or two into Gherkin, implementing them, then discovering more examples and exploring those a bit, etc.

It would be great if there were a way to communicate that the actual practice looks more like continuous collaboration than linear steps.

@lunivore

This comment has been minimized.

Copy link

commented Sep 6, 2019

@sebrose

This comment has been minimized.

Copy link
Member

commented Sep 8, 2019

Thanks for writing this, Matt.

As you know Gaspar and I went with Discovery, Formulation, and Automation. 鈥淒iscovery鈥 because 鈥渄eliberate discovery, 鈥淎utomation鈥 because we have a constant battle with BDD being confused with testing.

鈥淔ormulation鈥 was harder. I explained how Gaspar convinced me in our book 鈥淒iscovery鈥:

鈥淲hen I first started working with G谩sp谩r, I wondered why he kept using the word 鈥渇ormulate鈥. It鈥檚 not a term used by software professionals in general, or BDD practitioners in particular. He explained that it was the best word that he had found to describe the process of turning concrete examples into business-readable documentation. I was pretty sure there must be a better word, so I went away to try to think of one.
I tried substituting with 鈥渢ranslate鈥, but there鈥檚 a lot of creative energy required to write a good BDD scenario. 鈥淭ranslate鈥 didn鈥檛 do it justice, and nor did 鈥渃onvert鈥.
The Merriam_webster dictionary defines formulate as: to put into a systematized statement or expression. This is an accurate description of what we do when we convert examples into scenarios. This is an important task that is uniquely focused on by BDD practitioners and it deserves a precise name. Formulation is ideal!鈥

The three practices we took directly from Liz鈥檚 work (鈥淪tep away from the tools鈥 rather than 鈥淭hree headed monster鈥).

I鈥檓 with Tom with respect to the imperfection of naming, and with Liz that consensus may not be attainable. It feels like we鈥檙e getting to one of the later stages in Arlo鈥檚 naming process.

The fourth practice feels useful. I need to think about how it fits into the overall picture. 鈥淗abitation鈥 certainly has a lot of good associations as a name. I don鈥檛 have Gojko鈥檚 book to hand, so will have to compare your words with his at a later date.

Finally, I strongly agree with Richard鈥檚 observation about the iterative nature of the work. It would be good to make this clearer.

@gojko

This comment has been minimized.

Copy link

commented Sep 8, 2019

how about 'documenting'? after a conversation/exploration, document the result.

also, instead of habitation, how about iterating or revising? that's kind of suggesting a recurring process of cleanup and revision?

@mlvandijk

This comment has been minimized.

Copy link
Member

commented Sep 10, 2019

@mattwynne Preview works as expected imho. You get a full preview of the docs and have to navigate to the relevant page(s) though. What, in your opinion, isn't working?

@mlvandijk
Copy link
Member

left a comment

Suggestions on details, as I'll leave it to you all to describe BDD and it's terminology. Overall content is clear to me, but I'm not entirely new to BDD concepts anymore.

content/docs/bdd/_index.md Outdated Show resolved Hide resolved
content/docs/bdd/_index.md Outdated Show resolved Hide resolved
content/docs/bdd/_index.md Outdated Show resolved Hide resolved
content/docs/bdd/myths.md Outdated Show resolved Hide resolved
content/docs/bdd/overview.md Show resolved Hide resolved
content/docs/bdd/overview.md Show resolved Hide resolved
content/docs/terms/_index.md Outdated Show resolved Hide resolved
@@ -6,4 +6,107 @@ menu: main
iconClass: fas fa-comments

This comment has been minimized.

Copy link
@mlvandijk

mlvandijk Sep 10, 2019

Member

What does this front-matter tag do?

This comment has been minimized.

Copy link
@mattwynne

mattwynne Sep 16, 2019

Author Member

I think it adds an icon for this section on the main nav on the left?

---
title: Terminology
menu: main
collapseChildren: true

This comment has been minimized.

Copy link
@mlvandijk

mlvandijk Sep 10, 2019

Member

What does this front-matter tag do?

This comment has been minimized.

Copy link
@mattwynne

mattwynne Sep 16, 2019

Author Member

I have no idea - I was cargo-culting / copy-pasting from another main section.

content/docs/bdd/_index.md Show resolved Hide resolved
mattwynne and others added 4 commits Sep 16, 2019
grammar
Co-Authored-By: Marit van Dijk <mlvandijk@gmail.com>
grammar
Co-Authored-By: Marit van Dijk <mlvandijk@gmail.com>
Add Marit's feedback
Co-Authored-By: Marit van Dijk <mlvandijk@gmail.com>
grammar
Co-Authored-By: Marit van Dijk <mlvandijk@gmail.com>
@mattwynne

This comment has been minimized.

Copy link
Member Author

commented Sep 16, 2019

@mattwynne Preview works as expected imho. You get a full preview of the docs and have to navigate to the relevant page(s) though. What, in your opinion, isn't working?

@mlvandijk it does seem to be working again now, so I'm not sure. Previously, the link from the build check didn't seem to be showing the latest changes - it just showed the old, very short, index page for BDD from the master branch. Let's ignore it and hope it doesn't happen again :)


Over time, as your living documenation and codebase grow together, a symbiotic relationship develops between them. The documentation reflects the behaviour of the code, giving the whole team confidence about exactly what the system does. The code reflects the documentation, with rapid feedback for the developers if the code's behaviour strays outside the boundary defined by the living documentation.

This is where the investment of all that discovery, formulation and automation work pays off. The team are able to confidently and rapidly adapt the system --- and it's documentation --- to meet the business' evolving needs.

This comment has been minimized.

Copy link
@cbliard

cbliard Sep 17, 2019

I think there is a typo here

Suggested change
This is where the investment of all that discovery, formulation and automation work pays off. The team are able to confidently and rapidly adapt the system --- and it's documentation --- to meet the business' evolving needs.
This is where the investment of all that discovery, formulation and automation work pays off. The team are able to confidently and rapidly adapt the system --- and its documentation --- to meet the business' evolving needs.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can鈥檛 perform that action at this time.