The chapter explains that effective BDD documentation is not about piling up feature files, but about organizing them so they stay readable, maintainable, and useful over time. Feature files should describe coherent functionality rather than mirror user stories, because stories are temporary planning tools while rules and scenarios are the enduring documentation of behavior. As a product grows, the documentation must evolve with it: files may be split, renamed, moved, or deleted so that the structure continues to match the team’s current understanding of the domain.
A major theme is separation of concerns. The team learns to group scenarios by business capability, not by delivery history, and to keep illustrative scenarios focused on one rule while reserving journey scenarios for high-level end-to-end paths. The chapter also shows how Gherkin tags become part of the documentation, not just a technical convenience: they can mark manual scenarios, automation status, external identifiers, or other meaningful classifications. Because tags and domain terms can become obscure, the chapter recommends maintaining a glossary as a shared source of truth for business vocabulary and tag meanings.
The final guidance is about navigation and audience. Feature files should be arranged in a folder hierarchy that helps readers move from broad business areas to specific details, with shared functionality documented once and referenced where needed. Different stakeholders may need different views of the same system, so documentation can be structured to support targeted audiences through folders, tags, and careful naming. Overall, the chapter presents living documentation as something deliberately curated for clarity, discoverability, and shared understanding across business and delivery teams.
Traditional documentation
WIMP documentation
Customer domain documentation
Links across folder hierarchy
Summary
User stories are transient artefacts used to facilitate discussion, development, and delivery, not a core concept that persists in the system’s documentation
Feature files provide stable, navigable documentation when each one documents an area of coherent functionality
The team’s evolving understanding and usage of domain terms should be recorded in a glossary
Gherkin tags are very flexible and should be used to capture information that doesn’t fit into the main flow of a feature file’s natural language documentation
Journey scenarios are essential to document how the system functions as a whole
Leverage the file system to organize your documentation, keeping it easy to find information
Feature files provide documentation that is understood by business people, but you may need to provide several feature files to satisfy diverse business perspectives
FAQ
What is the difference between a user story and a feature in BDD?User stories are planning tools and placeholders for conversation during discovery, while features describe coherent product functionality. Once a story has been refined into rules and scenarios, the story itself has little or no lasting value as documentation.Why should feature files be organized by functionality instead of by user story?Organizing by story reflects the order of delivery, which is not useful for readers of living documentation. Organizing by coherent functionality makes the documentation more stable, easier to navigate, and more valuable to both business and delivery teams.How large should a feature file be?There is no strict size limit, but feature files should not be allowed to grow indefinitely. They should remain focused on a single area of behavior so they are easier to consult, maintain, and understand.What is separation of concerns in feature documentation?Separation of concerns means keeping different business capabilities in separate feature files when they represent distinct responsibilities. For example, blocklisting and pay-on-collection are related, but they are different concerns and are best documented separately.Why should domain terminology be documented in a glossary?A glossary provides a single place to explain the domain terms used across feature files. This helps readers understand the documentation without searching through many files and supports a shared understanding of the business language.How should Gherkin tags be treated in documentation?Tags are part of the documentation and should be understandable to all stakeholders. They can be used to group scenarios, mark manual checks, or support other useful classifications, but they should be documented and used sparingly.What is the purpose of the @manual tag?The @manual tag indicates that a scenario is verified by manual checks and should be excluded from automated test execution. It is a team-defined tag, not a built-in Gherkin or Cucumber tag.What are journey scenarios used for?Journey scenarios document a high-level user journey across multiple behaviors, giving an overview of how a user reaches a goal. They are useful for big-picture understanding and smoke testing, but should be used sparingly because they are slower, harder to debug, and more costly to maintain.How should shared behaviors be documented across multiple features?Shared behaviors should be documented in one place rather than copied into multiple feature files. If another feature depends on them, the dependency can be noted in the feature file description along with the name and relative path of the shared feature file.How should feature documentation be organized for different audiences?Documentation should be structured so that each audience can easily find what is relevant to them. This can be done using folders, subfolders, or tags, and may include separate areas for things like APIs or audience-specific feature sets.
pro $24.99 per month
access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
Effective Behavior-Driven Development ebook for free
