liveBook · Manning

Chapter 10: Organizing the documentation

What you will learn in chapter 10 of Effective Behavior-Driven Development

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

What it builds on

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Key terms: feature files, target audiences, file system, tagging

10.10 Summary

Where this is used later

Concepts explained in this chapter

← Chapter 9: A new user story Chapter 11: Coping with legacy →

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.