We are an inventory management system product company. We used, and still use, agile user stories for writing requirements and communicating them to the development team. During the initial stages we didn't think so much about the correct method of documentation, so we just have documents from each Sprint that contains all the stories for that Sprint.

However, we are now scaling and recognize that our old method is messy. Since documentation is based on Sprint, there is a lot of repeated stories and it's hard to find information we need based on that.

We decided on a new method of documentation based on system structure, so each module within the system will have a page and sub-pages that describe features in that module. We moved stories from old documents and distributed it across module pages based on its relevance to that module.

Should we even use stories for system documentation, or there is another way?

4 Answers 4


Stories, often User Stories, are usually a placeholder for a conversation. They start by capturing the requirement, but then you need to discuss the details. That's the refinement part of the requirement. This generates documentation usually, starting from a high level down to a detailed level, depending on each use case.

Sometimes you add high level stuff, like diagrams, sketches, a phrase here and there. Sometimes you have to go in fine details, specifications, rules that need to hold true, etc. Agile is about doing just as much as needed and just in time to implement the requirement. More than that would be considered waste, because the documentation would not add more to the understanding. Also, documentation changes with time and needs to be maintained. The more you have, the more effort to keep things up to date.

There needs to be a balance. And unfortunately that depends on the project.

What you use should be tailored to the needs of the product, the development team and stakeholders. If you need more details and something more long lived, then capture pages of documentation for each module of your application, like you described already. Start from architectural diagrams and dig deeper into modules or subcomponents, maybe by capturing a description of the functionality with lists of acceptance criterias for each. Anything you believe is needed for later on when you want a reminder of things and you are already many sprints down the road from the one you build the feature in.

Just remember to keep things in check. Not to much documentation, or it will become outdated and require a lot of effort to be maintained.


User stories are often an effective tool for capturing what end users need to be able to achieve with the system, and, as Bogdan says in their answer, a good placeholder for conversations between the team and the stakeholders and within the team. However, I don't find them suitable for documenting the state of the system in the long-term. The effort needed to maintain old user stories as the system evolves usually outweighs the value in doing so. Treating user stories as a delta between the current state of the system and the desired state of the system is a better use for your user stories.

However, there is still a need to describe what you have built. And there are several tools that you can use to achieve this. Unfortunately, there is no "correct" structure, tool, or method for this.

One place that I would look would be towards architectural documentation. There are plenty of sources out there for what good architectural documentation is, including standards like ISO/IEC/IEEE 42010 Software, systems and enterprise — Architecture description. Documenting Software Architectures: Views and Beyond offers some alternatives.

I've had good luck adopting the arc42 documentation structure, using C4 modeling for visually representing the system, and dropping into UML, rarely, when the additional detail is necessary.

In the end, the only people who will be able to assess the quality of any kind of documentation are the people who consume it. You will have to work with your stakeholders to understand the information that they believe would be helpful and find ways to expose that information to those people.


There are a number of challenges associated with documentation:

  • Keeping the documentation up to date
  • Ensuring the documentation accurately reflects the product

A great way to achieve both of these things is use an approach like Behaviour Driven Development (BDD).

Approaches like BDD make the documentation of the system a part of the process of development. They also use tests to validate that the documentation matches the real behaviour of the system.



Should we even use stories for system documentation, or there is another way?

No, you should absolutely not use user stories (by which you presumably mean items in Connextra format) or the Sprint Backlog as documentation. User stories are not designed to be used as documentation, and Sprints are just temporary containers to hold Sprint Backlog items for the duration of the Sprint. While you could conceivably use specification documents instead of user stories as Product Backlog items, that too is not a particularly good idea for iterative or incremental development frameworks such as Scrum.

Documentation should be part of your Definition of Done for each Increment. This is true whether you use user stories or some other format for your backlogs. You should also evaluate other agile practices like test-driven development (TDD) or behavior-driven development (BDD) that promote "executable documentation" to accurately describe the current system instead.

Consider your optimal strategies for storing retrieving documentation first. Then evaluate your best options for creating and maintaining it as "living documentation" rather than a functionally-separate deliverable from the product itself. That kind of decoupling ultimately creates friction, stale or ineffective documentation, and various forms of technical debt.

Why Not Store Documentation in User Stories?

Understanding User Stories

User stories, especially those in the most common format, generally look like this:

As a [persona or value-consumer],
I want [functionality or feature]
so that [value proposition with implied solution space].

These types of stories serve a few different purposes. Some of the most important are:

  1. Provide an easy-to-follow synopsis.

    A user story is not a specification document! It's a conversation placeholder to facilitate discussions by the development team, and between the developers and the stakeholders. It describes the viewpoint, objective, and context of a feature sufficiently to form an initial plan and a level-of-effort estimate. It also gives people a sort of shorthand to briefly convey the intent and scope of a unit of work.

  2. Define constraints or boundaries so that the solutions considered are "the simplest things that could possibly work."

    "So that..." explains why a given feature has potential value from the point of view of the defined persona. Since there are often many ways to accomplish any given goal, it often helps to define a context that guide potential solutions. Asking What do you want? without also asking How will that help you? doesn't help the team or the stakeholders measure against an objective outcome.

  3. Good user stories leave implementation details up to the developers.

    Specification documents often explain what (and sometimes how) in exhaustive detail, but almost never explain why. That lack of context is what leads to change control problems or projects that successfully deliver what was asked for without delivering what was actually needed.

Scrum itself has nothing to say about the format of the Product Backlog. Instead, it says that there can only be one Product Goal at a time, and that:

The Product Backlog is an emergent, ordered list of what is needed to improve the product.

Given that, you could certainly populate the Product Backlog with detailed specifications rather than user stories. However, detailed specifications rarely promote agility because they are not usually considered negotiable or adjustable in scope, both of which are extremely important aspects of agility in product development work. Big, upfront development (BUFD) planning is a frequent source of project failure. In contrast, small, independent, and negotiable work items that leave implementation details to the last responsible moment are better at empowering teams while also enabling projects to embrace "changing requirements, even late in development."

In addition, when used as conversation placeholders user stories help "[b]usiness people and developers...work together daily throughout the project." The persona or value consumer in Connextra format can provide valuable insight on who the development team needs to collaborate on the business side. That could be a stakeholder or a customer, but in either case it promotes the following agile values:

  • Customer collaboration over contract negotiation

  • Responding to change over following a plan

Sprints are Ephemeral Time Boxes for Backlog Items

By definition, Sprint Backlog items must:

  1. Fit into a single Sprint.
  2. Meet the Definition of Done before they can be considered complete.

Neither the individual Product/Sprint Backlog items nor the delivered Increments should carry any historical data; this includes documentation. These items either deliver a Sprint Goal that advances towards the Product Goal or they do not. The Sprint itself is simply a time-constrained container in which incremental or iterative work is done. When the time box expires, the Sprint "container" is emptied, and refilled with the work planned for the current iteration as determined by the Sprint Planning event.

Put another way, the previous Sprint is gone forever. Poof! Vanished! Finis! All that's left behind are the completed Increments (if any), and whatever process improvement tasks or goals that came out of the Sprint Retrospective.

While some tools might push you into placing documentation into Sprint artifacts, the framework itself suggests this is an anti-pattern. Any documentation should instead be part of the Definition of Done, and ideally designed to:

  1. Be easy to look up and retrieve.
  2. Embrace change in the product as it evolves.
  3. Avoid becoming an historical artifact or a "dead tree."

Let's look at some alternatives.

Recommended Approaches to Documentation

Documentation is essential, but agile documentation doesn't usually resemble the "dead tree" tomes put together by technical writers. Instead, most agile frameworks use one or more of the following techniques:

  1. Executable documentation.

    This is especially true in software projects, where tests should be designed to communicate functionality and intent. Behavior-driven development (BDD) frameworks like Cucumber use Gherkin to define living documentation in high-level, business-friendly grammar to facilitate tests that describe and document features using the business domain rather than the low-level details the developers implement in executable step definitions. Executable examples in comments in Python using doctest are also excellent approaches to keeping documentation up-to-date.

    This approach basically ensures that as the code base evolves, the documentation evolves with it. Changing system behavior should cause your executable documentation to fail, which prevents drift between the system and its documentation.

    As long as your tests focus on what and why rather than how, executable tests are your best bet.

  2. Documentation-oriented comments.

    Again, this is more software-oriented, but comments are important. Part of your Definition of Done should include adding useful documentation to your code base, changelog, and README files, or other artifacts.

    Descriptive RSpec tests run in --format documentation mode, semantic comments using YARD tags, especially the @example tag, allow you to write tests and comments that can pull double duty as documentation. Not every language supports these types of tests or comments, but many do.

    If your language doesn't support either executable comments or documentation embedded in code, then you can still write good comments. These should be done with documentation in mine, e.g. explaining what a module does, or why a particular piece of code is written a particular way. Well-written code is generally self-documenting for developers, but well-written comments explain value. For example:

     # Useless comment follows, assuming you know what a and b hold.
     # If not, use better self-describing variable names.
     # swap +a+ and +b+ variables
     a, b = b, a
     # Useful comment because it explains *why* this code is here,
     # how it works, and why it might be non-intuitive.
     # Takes no arguments because the lambda is a closure and gets
     # its values from the current context. Assigned to a variable
     # that can be passed around to collaborator objects while
     # effectively memoizing the values for this User instance.
     @old_enough_to_drink =
       ->{ (current_age_in_years - legal_drinking_age) >= 0 }
  3. Define a documentation checklist for each Increment in the Definition of Done.

    This is useful for any product, regardless of whether it's software or not. For example, part of your Definition of Done might say:

    Update each of the following documents to reflect the current behavior of the product before marking the Increment complete:

    • [ ] Product Wiki
    • [ ] User Manual
    • [ ] Technical Support Manual

    Because this is part of the Definition of Done, it makes documentation a perennial set of tasks for each feature or change during development instead of something that has to be tracked separately or carried as historical data as part of a backlog item or user story. It also neatly avoids the anti-pattern of tracking Sprints themselves as first-class historical artifacts.

Most projects also benefit from having a central repository for documentation. That may be a wiki, a manual written in Google Docs, manual pages written in Markdown and stored in Git, or whatever else is appropriate and useful for your project.

The point isn't that there are specific places or formats that are "best." Rather, the point is that the project should define how documentation will be searched and maintained, and the team should agree on how to implement that within their workflow. In general:

Living documentation > stale documentation > no documentation.

In addition:

Executable documentation > inline documentation > decoupled documentation > no documentation.

In short, consider your optimal strategies for keeping the documentation aligned with incremental or iterative changes to your product. Do your best to keep documentation tightly coupled with development in order to ensure that it doesn't grow stale or become an afterthought. If executable documentation isn't an option, then the Definition of Done is most likely your next best bet.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.