Specification by example

What Hacker News says

1. basicwolfJan 2025
   Hello HN,

   I'd like to share an idea and a library that implements it.

   As a fan of "Specification by Example" (as described in Gojko Adzic's renowned book), I faced numerous challenges trying to introduce these ideas at work or in hobby projects. Surprisingly, the most challenging part was writing specifications and examples in Gherkin/Cucumber syntax and producing readable living documentation out of them.

   I believe that the Given... When... Then... format is not the best for user-facing documentation. Personally, I find novel-like narratives, filled with code examples, design decisions, and diagrams, much more appealing. The question was: how can we ensure that the documentation reflects the current state of the system? That is how the "Testified Documentation" was born.

   What if we combine something already present and widely adopted by developers - automated tests and documentation generators? In a nutshell:

     1. We start the implementation once the business/community need is clear and there is a shared understanding.
     2. We briefly document the new feature and reference (so far non-existing) tests.
     3. We write the tests.
     4. We implement the feature.
     5. We repeat steps 2-4 until the feature is fully implemented and documented.
     6. We have an up-to-date document that explains how the system works.
   

   This might also be appealing to open-source projects, which we document anyway. We can ensure that documentation is up-to-date by testifying it!

   And finally: sphinx-testify is a very simple extension to the Sphinx documentation generator that enables the ideas described above.

   I would appreciate your opinion, criticism, and thoughts!

   Show morethread
2. bunderbunderSep 2018
   I'm rather fond of a book, Specification by Example by Gojko Adzic, that's partially a manifesto for, and partially a guide to, doing this.
   thread
3. tomashmOct 2025
   tldr; Adding key examples to a specification makes it much easier to understand.

   I learned programming with Pascal at university. It had a very formal, math-like syntax, complete with BNF-style grammar.

   The next course used the famous K&R book (The C Programming Language), and what a breeze that was! It taught by showing lots of relevant, working examples.

   Since then, I’ve realized that while examples aren’t a substitute for a clear specification, well-chosen examples make specs far easier to grasp.

   I recommend reading Gojko Adzic’s thoughts on this (https://www.linkedin.com/in/gojko/). He’s the author of Specification by Example.

   He argues that identifying and refining key examples is a great way to raise the quality of documentation and shared understanding.

   Show morethread
4. rgoulterApr 2019
   A common anti-pattern with Given-When-Then has the Three Amigoes collaborating on scenarios that are stored as acceptance criteria in user stories.

   I agree with this. Writing Cucumber/Gherkin scenarios is extra effort if the Cucumber files themselves aren't used/read elsewhere. -- It'd be simpler to embed "Given/When/Then" statements within test code (like RSpec).

   I'd emphasise that Gojko Adzic's "Specification By Example" suggests discussing examples before refining to a specification; that may get around the author's complaint that non-table formats don't allow for important cases.

   That said, "Given/When/Then" is hardly magical, so doesn't deserve much praise/criticism itself. Any test involves "do an action, check the result" (with "setup the system" and "cleanup" being implied). Sometimes called "Assemble, Act, Assert". "G/W/T" is just a neat, consistent format for describing behaviour in English. A table of values specifies some computation; the column titles help to describe that behaviour.

   Show morethread
5. awinderJun 2018
   I just got through https://www.amazon.com/Specification-Example-Successful-Deli... which pitches a common structure (Given-When-Then) for describing behaviors and getting them out of your ticketing systems, which are not designed for knowledge explanation long-term, but are more for describing active work in short term.

   BDD is almost a poisoned term at this point because it’s become associated with tooling and opinionated holistic processes. But if you think of Specification by Example as readmes with a Given-When-Then structuring, then you have a strategy (document before writing) combined with a language definition to assure your strategy is executed at the right level of detail. Which solves the entangled problem of what do I do first (document) with what level of detail (enough to describe all the input behaviors to whatever I’m working on)

   Show morethread