The vocabulary of living product specs
Definitions of the terms Specsight uses — how they relate, where they came from, and how they fit into a living product specification.
Behaviour-Driven Development
A software development practice where behaviour is described in a structured format (typically Gherkin) that can be read by stakeholders and executed as automated tests.
Context, Action, Outcome
A structured format for describing product behaviour. Precise enough to be unambiguous, plain enough for anyone on the team to read — without the machine-oriented syntax of BDD.
Doc-as-Code
A documentation philosophy that treats docs the same way as code: stored in version control, written in plain text, reviewed in pull requests, deployed via CI. Specsight goes one step further and derives docs from code itself.
Documentation Debt
The accumulated cost of outdated, missing, or unreliable documentation. Like technical debt, but for the gap between what your product does and what your team can describe.
Documentation Drift
The gradual divergence between written documentation and the product it describes. Different framing of the same problem as specification drift, more common in everyday usage.
Edge Case
A scenario that describes unusual but valid behaviour — the conditions at the edges of what the feature supports. Often the source of support tickets.
Error Scenario
A scenario that describes what the product does when something goes wrong — invalid input, failed validations, blocked actions, or system-level failures.
Gherkin
A structured syntax for describing software behaviour, centred on Given-When-Then clauses. Designed to map directly to automated test steps.
Happy Path
A scenario that describes the expected, successful flow of a feature — what happens when everything goes right and the user stays on the main track.
Living Documentation
Documentation that is structurally incapable of falling out of sync with the product, because it is derived from the code rather than written separately.
Product Specification
A written description of how a product behaves — feature by feature, scenario by scenario. Distinct from a technical spec, which describes implementation.
Scenario
A single plain-language description of how a product behaves in a specific situation. The atomic unit of a living product specification.
Single Source of Truth
A canonical, authoritative version of information that everything else defers to. For product behaviour, the only true source of truth is the code itself.
Specification Drift
The gap that opens between a written specification and the product it is meant to describe — widens with every release that nobody remembers to document.
User Story
A short statement of a feature from the perspective of the user, typically following the format “As a [role], I want to [action], so that [benefit].” A planning artefact, not a behaviour spec.
See these terms in practice
The Specsight demo shows real scenarios, features, and a complete living spec — generated from an actual codebase. No account required.