Traceable Details: illustrate and refine to a living documentation

Illustrate requirements with examples

User stories are refined using acceptance criteria before they are implemented. Acceptance criteria are sets of acceptance tests a user can perform to verify that the given user story was implemented as agreed. These tests are defined before implementation starts, and provide a detail specification to developers what to implement. Because of amount and level of detail, acceptance criteria are captured as late as possible before implementation start.

Acceptance criteria are often captured as abstract descriptions of expectations (e.g. “Should not allow duplicate user name”). However, illustrating these expectations with examples can remove ambiguities and help building a shared understanding. Examples can be given in different ways and formats, depending on the type of aspect an acceptance criteria describes:

UI scribbles and images are best to describe user interface design and expectations

Examples of user input data and output data are good for describing business logic and formulas

Examples of user actions and responses of the system are good for describing business rules and workflow

Refine the specification

Examples for acceptance criteria can be further formalized to allow automatic validation against the developed product. Following the red-green-refactor cycle of test-driven-development (tdd), developers are automating formalized acceptance criteria examples as tests that fail, before implementing the new behaviour into the system to make the tests pass. This extends the test-driven-development cycle from unit tests confirming technical design decisions to acceptance tests confirming business requirements.

When automating validation of acceptance criteria, it is important to preserve their business readability(automating without changing the specification). The validation can occur continuously with each source code change, which provides additional confidence when evolving the product.

Following this workflow provides an always up-to-date description of how the system works, which is readable for the business and the team.

SpecLog supports this workflow by allowing to link acceptance criteria formalized for automation, such as SpecFlow feature files, to requirements. Automated acceptance criteria can be linked from different sources:

A folder or fileshare accessible from the server

A source code repository hosted on Team Foundation Server

Further source control systems will be supported in the future.

Build a living documentation

The product backlog collects epics and user stories describing possible next increments of the system under development. Their granularity and level of understanding is heterogenous, depending on how close they are to implementation. Requirements are continuously refined, yielding fine grained user stories with detailled acceptance criteria and examples when they are “done”.

Automating acceptance criteria examples of user stories preserve their value after they have been implemented, as they are serving as an always up-to-date and business readable documentation of system behaviour. However, their level of detail is so low, that the overview of “done” user stories becomes harder as their number increases.

To build a comprehendable and manageable “living documentation” of the system, a functional feature tree of the system needs to be evolved, where user stories with their automated acceptance criteria are migrated to, when they are “done”.

That said, there are two important views on the requirements of a product, which have to be managed differently:

The view into the future: provided by the product backlog, that shows possible next increments of the system, and is optimized for managing the evolvement of the system. This view is continuously refined based on customer feedback and emerging business needs.

The view into the past: provided by the living documation, that shows implemented features of the system, and is optimized for managing an overview of the existing system. This view is continuously validated with automated acceptance tests to ensure it is up-to-date.

SpecLog is designed to supporting managing both views of requirements and migrate from the future view to the past:

Different types of requirements can be captured, to distinguish between view into the future and view into the past.

Hierarchies and relationships can be defined between requirements to build a feature tree and associate existing features with previous product increments.

Acceptance criteria can be moved from one requirement to another to support migrating user stories into the feature tree.

Maps of requirements can be built to help maintaining overview of complex product feature trees.

Automated acceptance criteria (such as SpecFlow feature files) can be linked to requirements, to support continuous validation of the living documentation.