Build a living Documentation

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.