Living Documentation: Why Your Scenarios Aren't Documentation Yet

"Didn't we already have something like this?"

Deepa is four weeks into the team, and she's the one who asks the question that stops every Three Amigos session eventually. Someone thinks maybe there's a scenario for this already. Nobody's sure. Tom starts scrolling through the feature files. Two minutes pass. Five. The meeting keeps going without an answer, and forty-seven scenarios later, nobody found it.

The obvious read is a findability problem: bad folder structure, missing tags, no search index worth using. More organization sounds like the fix.

Except a perfectly organized suite might not have surfaced that scenario either. It wasn't filed under a missing tag. It was filed under a different name for the same concept, and no folder structure catches that. Nobody's curating this suite. That's the gap forty-seven scenarios and a five-minute search exposed.

That distinction matters more than it sounds like it should, because plenty of teams treat "we have executable scenarios" and "we have living documentation" as the same claim. They're not. Executable scenarios are a necessary condition for living documentation. They are not a sufficient one. Without active curation (someone owning accuracy, someone keeping the vocabulary aligned), the suite doesn't become documentation. It becomes a test archive that happens to be readable, until it isn't.

Every scenario is a one-way door

Feature files only grow. Teams add a scenario when a new case shows up. They almost never remove one, because removing a scenario feels like removing test coverage, even when the coverage is redundant. Seb Rose's Effective Behavior-Driven Development names this directly: without a deliberate organizing principle, a Gherkin suite accumulates the way a junk drawer accumulates, not because anyone decided it should, but because nothing pushed back against it.

The accumulation is less a maintenance failure than a structural default. Adding is the path of least resistance. Consolidating requires someone to notice overlap, decide which version is correct, and do the work of merging. That work competes with the next sprint, every sprint, forever.

The failure mode that follows is quieter than an outright bug. On one developer forum, someone described the exact shape of it: their team's feature files had drifted to the point where only QA opened them anymore. QA wasn't more invested in documentation than anyone else on the team. QA's workflow was the only one that still forced someone to open the file.

That's the tell. A suite is still passing. It's still green. And it's already stopped being anyone's source of truth except the person whose job is to run it.

Three names, one concept

Here's what cost Deepa her two minutes. Somewhere in the suite is a scenario that covers the same behavior she was looking for, reassigning a job to a different technician mid-shift. It exists. It's filed as "swap technician" in one file and referenced as "reroute assignment" in another, and Deepa searched for neither, because she didn't know they meant the same thing.

This is what practitioners sometimes call the vocabulary problem, and it's more corrosive than the file-count problem because it's invisible until someone hits it. As one developer put it in a forum discussion, this kind of misalignment lives as tribal knowledge, absorbed by whoever's been around long enough, never written down anywhere a newcomer could find it. Deepa hadn't been around long enough.

Structure doesn't fix this. You can have five pristine, well-tagged feature directories, and the vocabulary drift still happens inside them, because tags describe where a scenario lives, not what concept it encodes.

Three feature files, three names, one business rule. Deepa searched for one of them. The scenario she needed was living under one of the other two.

Deepa never searched for "reroute assignment" or "transfer ticket." As far as she knew, those were different things, not two names for the rule she already needed. The suite had the coverage all along. It didn't have a shared language for what it covered.

The five decisions nobody makes

None of this is a Gherkin problem so much as a governance one. It has an answer: not a tool, not a framework, five specific decisions a team has to make on purpose, because none of them happen by default.

Cyrille Martraire frames this kind of curation as a design discipline, not a chore. A suite doesn't stay alive on its own, someone has to keep deciding what still belongs in it. Here's what that discipline breaks down into, decision by decision.

Ownership. Someone is accountable for the suite's accuracy: not write access, accountability. In practice this works best split two ways: one person tracking whether the implementation still matches the scenario text, another tracking whether the scenario text still matches the current business rule. Neither person alone sees the whole picture.

Maintenance trigger. The specific event that forces a scenario review. A failed test is the obvious one. It's also the one that catches the least. The trigger that matters more is a business rule change landing in a sprint: the moment it's accepted, the scenario update becomes part of the story, not an adjacent task someone might get to. Gojko Adzic makes this point precisely in Specification by Example's chapter on evolving a documentation system: the teams whose suites stayed accurate had built explicit triggers. The teams whose suites went stale had assumed the connection between a business change and a scenario update was obvious. It wasn't. Not once anyone was three tasks deep into a sprint.

Cadence. A review schedule that runs independent of triggers (the suite's heartbeat). Quarterly is usually the right rhythm: frequent enough to catch drift before it compounds, light enough not to compete with the next sprint's actual work.

Vocabulary review cadence. Its own schedule, decoupled from the accuracy review, because vocabulary drift moves slower and is easier to miss. This is where someone checks scenario terminology against what the business says out loud, and where a new hire's confusion, like Deepa's, gets treated as a signal instead of an onboarding hiccup.

Organization principle. The structural precondition for the other four. A maintenance system applied to a flat, unstructured suite costs more to run and finds less. Feature-based directories, organized by capability rather than sprint or ticket number, make every other decision on this list executable.

None of these decisions is complicated on its own. Together, they're the difference between "we have Gherkin" and "we have documentation." Machiel van der Bijl's well-known critique of BDD-as-documentation (that it's hard to scale and, in practice, ends up serving testing more than communication) is correct about what happens when these five decisions don't get made. It's not an argument against BDD. It's a description of BDD without curation.

Tools that structure requirements before they become Gherkin, Speclr among them, can make the vocabulary-review discipline easier to enforce, but the discipline itself has to exist first.

What curated documentation is actually for

There's a version of this conversation happening right now in a completely different corner of software engineering. Teams building with AI coding agents are discovering that a stale spec does something worse than confuse a new hire: it produces confidently wrong code. An agent working from documentation that says "four-hour threshold" when the system now enforces two hours doesn't know it's wrong. It builds on what it was given.

That's the same failure as Deepa's search, wearing different clothes. A living documentation suite that's actually maintained (accurate, owned, vocabulary-aligned) does more than help the next developer who reads it. It becomes the structured, current context that lets anything relying on it, human or otherwise, act on what the system does rather than what it used to do.

Which is the real reason the five decisions matter. Call it BDD hygiene if you want, but what it decides is whether the spec still means something in five years, regardless of who, or what, reads it next.

Further Reading

Shift-Left with BDD: The Full Journey

Want the full, deployable system behind the five decisions? This course walks a team's suite from accumulation to a working maintenance system, start to finish.

View the course