Chapter 3. Living documentation


There are two popular models today for looking at the process and artifacts of Specification by Example: the acceptance-testing-centric model and the system-behavior-specification model.

The acceptance-testing-centric model (often called acceptance test-driven development, ATDD, or A-TDD) focuses on the automated tests that are part of the Specification by Example process. In this model, the key benefits are clearer targets for development and preventing functional regression.

The system-behavior-specification-centric model (often called behavior-driven development or BDD) focuses on the process of specifying scenarios of system behavior. It centers on building shared understanding between stakeholders and delivery teams through collaboration and clarification of specifications. Preventing functional regression through test automation is also considered important.

I don’t consider one of these models superior to the other; different models are useful for different purposes. The acceptance-testing-centric model is more useful for initial adoption if a team has many functional quality issues. When things are running smoothly, the behavior-specification-centric model is useful for explaining the activities of short-term and mid-term software delivery.

Why we need authoritative documentation

Tests can be good documentation

Creating documentation from executable specifications

Benefits of the documentation-centric model