Chapter 10: Organizing the documentation
The introduction explains why long-lived Gherkin feature files should stay focused and be organized before a growing collection becomes difficult to maintain.
After this chapter you will be able to
- Focused feature file documentation. Explain why feature files should remain focused even though their size is unrestricted: each documents part of the system’s behavior for as long as the system is in use, so it must be easy to consult and maintain.
- Early organization of feature files. Describe how to keep a growing collection of Gherkin feature files manageable: use familiar folder-and-file hierarchies, begin organizing while the collection is small, and revisit the structure as it develops.
- Stories and enduring requirements. Distinguish a user story’s role in planning a small increment from the lasting requirements and examples produced through discovery. Explain why the story may no longer be needed after delivery.
- Feature files by functionality. Justify organizing feature files around coherent product functionality rather than creating one file per user story. Describe how one story can lead to both new feature files and changes to existing ones.
- Separation of business concerns. Explain why customer blocklisting, customer collection, and pay-on-collection belong in separate feature files, and describe how the team groups the pay-on-collection rules.
- Evolving domain terminology. Explain why the team may need to rename concepts as its understanding of the domain deepens, even when it has tried to choose accurate terms from the start.
- Reader-centered feature organization. Describe the roles of rules, illustrative scenarios, and feature files, and explain why rules and scenarios may move between feature files as documentation grows.
- Shared domain glossary. Explain why the team creates a glossary for feature files and what it contains.
- Team-defined tag meanings. Distinguish the team’s meaning for @manual from a meaning built into Gherkin or an automation tool, and explain why tags belong in the glossary.
- Tags as scenario indexes. Explain that Gherkin tags annotate and group scenarios, making related scenarios easy to find, report on, or select for automated execution.
- Business readable tag choices. Justify choosing tags that convey business needs or stakeholder value, even when integration with project tools calls for additional tags.
- Scenario lifecycle tags. Explain how tags can represent a scenario’s automation lifecycle and how the section’s example tags distinguish unfinished scenarios from those considered done.
- External work item tags. Explain how a tag can record a connection between a plain-text scenario and a work item in an external ALM tool, such as a feature identified by its ID.
- Stakeholder-readable automation tags. Explain why automation-related tags should stay understandable to all stakeholders, even when they record a genuine execution need. Describe how high-level tags such as @manual and @browser can communicate quality-assurance risks.
- Shared tag maintenance. Explain how the team should decide on, document, and retain scenario tags without sacrificing readability.
- Complementary scenario purposes. Distinguish illustrative scenarios, which show a specific business rule, from journey scenarios, which show how a user reaches a higher-level goal across many rules. Explain why the team rejected its restricted-customer journey.
- Selective journey documentation. Justify keeping only a carefully chosen set of journey scenarios and prioritizing illustrative-scenario automation. Describe their potential use as overviews of core processes and deployment smoke tests, alongside their costs.
- Business-facing feature boundaries. Explain why a feature has no fixed size and why feature files should represent distinct pieces of business functionality rather than only small pieces of behavior.
- Separate journey scenario files. Distinguish journey scenarios from illustrative scenarios and explain why they should be kept in separate feature files.
- Navigable feature file hierarchy. Explain why feature files need a navigable structure and how folders in source control can provide one.
- Documentation levels of detail. Explain how nested folders let readers find either a broad view of system behavior or more fine-grained rules.
- Single documentation for shared features. Explain why behavior used by several parts of a system should have one feature file rather than copies in each location.
- Documented feature dependencies. Describe how to record a dependency between feature files when organizing shared features.
- Audience-specific feature documentation. Explain why different stakeholders may need different feature-file documentation and how a team can organize it for them.
What it builds on
- Living documentation (chapter 6) · Introduces the idea of living documentation.
- Start with a user story (chapter 1) · Introduces starting BDD work with a user story.
- Rules vs. examples (chapter 3) · Introduces the distinction between rules and examples.
- A sample feature file (chapter 8) · Feature files as the place where the team writes its specifications.
- Documenting with a tag (chapter 9) · The use of a tag in feature-file documentation.
- The BDD approach (chapter 4) · The BDD approach’s formulation, automation, and implementation work.
- Setting the context (chapter 9) · The distinction between stated scenario context and context left implicit.
- Illustrative scenarios (chapter 7) · Illustrative scenarios as focused examples of behavior
Section by section
Introduction
The introduction explains why long-lived Gherkin feature files should stay focused and be organized before a growing collection becomes difficult to maintain.
- Focused feature file documentation: Explain why feature files should remain focused even though their size is unrestricted: each documents part of the system’s behavior for as long as the system is in use, so it must be easy to consult and maintain.
Why it matters: Focused files remain useful as documentation throughout the system’s life. - Early organization of feature files: Describe how to keep a growing collection of Gherkin feature files manageable: use familiar folder-and-file hierarchies, begin organizing while the collection is small, and revisit the structure as it develops.
Why it matters: Organizing a small collection is easier than untangling a large one later.
Key terms: feature files, documentation, focused, Gherkin feature files, source control, hierarchies of folders and files
10.1 User stories are not the same as features
This section explains why feature files should document coherent product functionality rather than mirror the user stories used to deliver it.
- Stories and enduring requirements: Distinguish a user story’s role in planning a small increment from the lasting requirements and examples produced through discovery. Explain why the story may no longer be needed after delivery.
Why it matters: It keeps temporary delivery plans from being mistaken for the product’s lasting specification. - Feature files by functionality: Justify organizing feature files around coherent product functionality rather than creating one file per user story. Describe how one story can lead to both new feature files and changes to existing ones.
Why it matters: Readers can find a product capability without reconstructing the order in which its stories were delivered.
Key terms: user stories, rules, scenarios, requirements, feature files, coherent functionality, living documentation, stability, navigability
10.2 Separation of concerns
The team reorganizes feature files by business concern and explains why living documentation should change as its understanding of the business changes.
- Separation of business concerns: Explain why customer blocklisting, customer collection, and pay-on-collection belong in separate feature files, and describe how the team groups the pay-on-collection rules.
Why it matters: Grouping rules by the business concern they govern makes the documentation easier to navigate as the system changes. - Evolving feature documentation: Describe how feature files, rules, and scenarios should change as the team’s understanding of the business problems changes.
Why it matters: A feature-file structure remains useful only if the team can revise it when its understanding improves.
Key terms: blocklisting, pay-on-collection, feature file, rule, documentation, feature files, rules, scenarios
10.3 Documentation evolves
The section explains why living documentation needs its terminology and organization refined over time, and how to refactor scenarios without losing behavior.
- Evolving domain terminology: Explain why the team may need to rename concepts as its understanding of the domain deepens, even when it has tried to choose accurate terms from the start.
Why it matters: Clear terms help the documentation reflect what the product actually does. - Reader-centered feature organization: Describe the roles of rules, illustrative scenarios, and feature files, and explain why rules and scenarios may move between feature files as documentation grows.
Why it matters: Organizing around readers makes the specification easier to navigate as it grows. - Tool-assisted scenario refactoring: Describe the kinds of documentation changes editors can help with and the more complex refactoring suggestions for which AI may be useful.
Why it matters: These aids can make documentation changes easier, but their suggestions still need review. - Safe refactoring checks: Explain the recommended checks before refactoring scenarios and what those checks help the team detect or review.
Why it matters: A refactor should improve the documentation without silently changing or removing what it specifies.
Key terms: terminology, domain, blocklisting, rules, illustrative scenarios, feature files, Gherkin, AI, refactoring, scenarios
10.4 Documenting the domain
This section shows how a shared glossary can explain the domain terms and tags used in feature files, and how the team can keep it useful.
- Shared domain glossary: Explain why the team creates a glossary for feature files and what it contains.
Why it matters: A glossary gives the team a common place to check what its feature-file language means. - Team-defined tag meanings: Distinguish the team’s meaning for @manual from a meaning built into Gherkin or an automation tool, and explain why tags belong in the glossary.
Why it matters: Documenting a tag’s agreed meaning prevents readers from mistaking a team convention for a tool-defined rule. - Keeping glossary definitions aligned: Describe how the team proposes to keep glossary entries aligned with feature files and shared understanding.
Why it matters: Checking both the terms and their explanations helps the glossary remain useful as the documentation evolves. - AI-assisted glossary review: Describe what AI can help do with a domain glossary and why people must still review its output.
Why it matters: AI can reduce glossary maintenance effort without becoming the authority on what the team’s terms mean.
Key terms: glossary, domain terminology, feature files, Gherkin tag, @manual, build process, domain, living glossaries, Markdown file, shared understanding
10.5 Tags are documentation too
Gherkin tags group and index scenarios for useful selection and reporting, but should remain readable to business stakeholders even when tools need them.
- Tags as scenario indexes: Explain that Gherkin tags annotate and group scenarios, making related scenarios easy to find, report on, or select for automated execution.
Why it matters: Useful tags make related scenarios easier to locate and let the team run or report on a relevant group. - Business readable tag choices: Justify choosing tags that convey business needs or stakeholder value, even when integration with project tools calls for additional tags.
Why it matters: Readable tags preserve the feature files’ value as documentation while still supporting the team’s tool-chain.
Key terms: Gherkin tags, scenarios, feature files, @fast, business readable living documentation, stakeholder value, tool-chain, tags
10.5.1 Tracking scenario automation lifecycle with tags
This section explains how tags can distinguish unfinished scenarios from completed ones so expected failures do not obscure the results of completed scenarios.
- Scenario lifecycle tags: Explain how tags can represent a scenario’s automation lifecycle and how the section’s example tags distinguish unfinished scenarios from those considered done.
Why it matters: The tags make unfinished work distinguishable from scenarios expected to pass. - Expected failures and readable documentation: Explain why failures from unfinished scenarios should be kept separate from completed-scenario results, and why the authors avoid an explicit @done tag.
Why it matters: Separating expected failures keeps completed-scenario results meaningful without cluttering the documentation.
Key terms: scenario automation lifecycle, @formulated, @inprogress, done, always green, @done, living documentation
10.5.2 Tagging scenarios with external identifiers
Explains how tags can link plain-text scenarios to external work items, and why teams should record only useful links.
- External work item tags: Explain how a tag can record a connection between a plain-text scenario and a work item in an external ALM tool, such as a feature identified by its ID.
Why it matters: A tag can keep a useful work-item link with the scenario even when the team edits scenarios as plain text. - Selective relationship recording: Justify recording only external work-item relationships the team will use, rather than tagging every scenario with its originating user story for traceability.
Why it matters: Keeping only useful references makes the scenarios less distracting to read.
Key terms: tags, external ALM tools, work items, readable, traceability, originating user story work item
10.5.3 Tagging scenarios with automation details
This section explains how scenario tags can convey automation needs and context without making living documentation harder for stakeholders to read.
- Stakeholder-readable automation tags: Explain why automation-related tags should stay understandable to all stakeholders, even when they record a genuine execution need. Describe how high-level tags such as @manual and @browser can communicate quality-assurance risks.
Why it matters: A tag is most useful when it helps the whole team understand the scenario rather than only helping the automation specialists. - Authentication context through tags: Describe why the team used @authenticated instead of either assuming authentication implicitly or repeating a Given step, and what else the tag made visible.
Why it matters: The example shows how a readable tag can clarify shared context while making related scenarios easy to identify. - Shared tag maintenance: Explain how the team should decide on, document, and retain scenario tags without sacrificing readability.
Why it matters: Shared decisions and documented meanings keep tags useful as documentation rather than letting them become clutter.
Key terms: automation-related tags, @manual, @browser, stakeholders, @authenticated, implicit context, Given an authenticated user, tags, glossary, readability
10.6 Journey scenarios
This section explains how a small number of journey scenarios can complement focused illustrative scenarios by showing a user’s path toward a goal, while avoiding unnecessary duplication and maintenance cost.
- Complementary scenario purposes: Distinguish illustrative scenarios, which show a specific business rule, from journey scenarios, which show how a user reaches a higher-level goal across many rules. Explain why the team rejected its restricted-customer journey.
Why it matters: The two kinds of scenario document different views of the system rather than replacing one another. - Selective journey documentation: Justify keeping only a carefully chosen set of journey scenarios and prioritizing illustrative-scenario automation. Describe their potential use as overviews of core processes and deployment smoke tests, alongside their costs.
Why it matters: A few well-chosen journeys can add perspective without overwhelming the focused documentation and automation. - Journey scenario presentation: Describe how journey scenarios may be written and distinguished from illustrative scenarios, including the trade-off of using Gherkin asterisks and the reduced need for concrete data.
Why it matters: The presentation can make a journey easier to read without obscuring the precision needed in rule examples. - AI-generated journey alternatives: Explain when AI-generated user journeys might provide the broader view without maintaining explicit journey scenarios, and what cautions apply to its suggestions.
Why it matters: An on-demand journey may supply the overview without adding another document to maintain, provided the result is checked.
Key terms: illustrative scenarios, journey scenarios, business rule, user journey, smoke tests, core business processes, asterisk, Given, When, Then
10.7 Structuring the living documentation
This section explains how business-facing feature files should reflect different scales of functionality and why journey scenarios belong apart from illustrative scenarios.
- Business-facing feature boundaries: Explain why a feature has no fixed size and why feature files should represent distinct pieces of business functionality rather than only small pieces of behavior.
Why it matters: It helps the team organize documentation around functionality that matters to its readers. - Separate journey scenario files: Distinguish journey scenarios from illustrative scenarios and explain why they should be kept in separate feature files.
Why it matters: Separating the files preserves the distinction between individual rules and broader stakeholder journeys.
Key terms: feature, feature files, business-facing, business functionality, journey scenarios, illustrative scenarios, fine grained rules
10.7.1 Navigation
This subsection explains how a folder hierarchy makes feature-file documentation easier to navigate and shows a starting layout for the WIMP project.
- Navigable feature file hierarchy: Explain why feature files need a navigable structure and how folders in source control can provide one.
Why it matters: Documentation is useful only if readers can find the behavior they need. - WIMP documentation layout: Describe the example folder layout for the WIMP documentation and how it can grow.
Why it matters: The example shows how to start with a simple structure without treating it as fixed.
Key terms: scenarios, feature files, source control, hierarchical tree of folders, glossary, journey scenario, feature file, subfolder
10.7.2 Zooming in and out
This subsection explains how nested folders let readers navigate living documentation at different levels of detail.
- Documentation levels of detail: Explain how nested folders let readers find either a broad view of system behavior or more fine-grained rules.
Why it matters: Readers can find the level of detail they need without wading through everything else.
Key terms: nested folders, root of the documentation, fine grained rules
10.8 Documenting shared features
The section explains how to keep shared behavior in one feature file and document which other features depend on it.
- Single documentation for shared features: Explain why behavior used by several parts of a system should have one feature file rather than copies in each location.
Why it matters: Keeping one description makes shared behavior easier to maintain as it changes. - Documented feature dependencies: Describe how to record a dependency between feature files when organizing shared features.
Why it matters: A documented dependency helps readers find the shared behavior even when its file sits elsewhere in the hierarchy.
Key terms: shared features, feature file, Gherkin, feature file description, dependencies, relative file path
10.9 Targeted documentation
This section explains how to tailor feature-file documentation so different stakeholders can find and read what is relevant to them.
- Audience-specific feature documentation: Explain why different stakeholders may need different feature-file documentation and how a team can organize it for them.
Why it matters: Documentation remains useful when each stakeholder can find the behavior and language relevant to them.
Key terms: feature files, target audiences, file system, tagging
10.10 Summary
Where this is used later
- (chapter intro) (chapter 17) · The product glossary as documentation of domain concepts.
- Scenario Resource pattern: managing test resources (chapter 16) · Tags attached to scenarios and their enclosing documentation.
- Not all journeys are informative (chapter 11) · The idea of journey scenarios.
- Organizing glue code (chapter 12) · The organization of living documentation, which need not match the organization of step definitions.
Concepts explained in this chapter
- tagAn @-prefixed metadata label that annotates and categorizes Gherkin elements.
- feature fileA feature file is a structured text file that expresses a software feature and its behavior scenarios in a format interpretable by BDD tools.
- journey scenarioA scenario that describes a complete user journey and the end-to-end flow through which a system delivers useful outcomes.
- capabilityThe set of capabilities and behaviors that a software system provides.
- glossaryAn alphabetical list of terms relating to a subject, accompanied by explanations of their meanings.
- user storyA user story is a concise requirement description expressing desired software behavior from a user's perspective.
- living documentationLiving documentation is documentation kept aligned with the current behavior of a software system through executable or continuously validated specifications.
- requirementsA requirement is a statement of a stakeholder need, constraint, or expected system behavior that guides solution development.
- documentationDocumentation is recorded information describing a system and its behavior for reference and maintenance.
- illustrative scenarioA concrete narrative describing a representative situation, context, and expected behavior for a business requirement.
- asteriskA Gherkin step marker that can introduce a step without explicitly stating Given, When, or Then semantics.
- business ruleA business constraint governing payment when a customer collects an order.
- incremental developmentA software delivery approach in which functionality is delivered in small, planned increments.
- scenarioA business-readable description of an example system behavior and its expected outcome.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
