Should I be using user stories as my documentation?

Question

I've just inherited a project and I'm forming a new team.

How it's been currently done is there is a list of user stories - these user stories have lots of tasks attached to them that the dev picks up. They also have a bunch of acceptance criterias and the tester writes test cases for each of them.

There are a few problems I'm finding with this - the user stories are never complete. The tasks get complete - but if someone suggests a feature that is related to that user story, the current process is to re-open and change the existing user story - to add a new task and modify the test cases to adapt.

It's also difficult to change anything in the system - anytime you change anything, you have to go through all the old user stories that are related to that part of the system and make sure you update the acceptance criteria. It's also hard to find information about the system - you have to find the right user story to figure out the business requirements.

Are user stories supposed to be used like this to document the system? I'm consider asking my business analyst to write specs independent of the user stories which will be used as the actual source of truth. Then the user stories are only used for communicating and managing what needs to be done for each sprint. Once they're closed, they are not maintained.

Answer 1

TL;DR

Should I be using user stories as my documentation?

No, most definitely not. A user story is a conversation placeholder, not a written specification or unit of documentation. Especially in software development, your "documentation" should comprise working code with descriptive names, comments, and tests that clearly describe how the system currently works, and how it's expected to work.

User Stories are Placeholders

You are misusing user stories if you're using them as specifications. In most agile systems, an iteration is a cycle or time box that expires. Iterative/incremental development requires that each activity within a time box be treated as independently as possible: you estimate effort based on how much work remains now, not where the team or project was some period of time in the past.

Revising past estimates, user stories, or acceptance criteria is an extremely whiffy project smell that indicates that user stories are being misused as something other than conversation placeholders or near-term planning guidelines to aid collaboration. Not only is this an anti-pattern, but as you've seen yourself this quickly becomes a time sink with no discernable value to the team or the project.

Value "Working Software" and Collaboration

The Agile Manifesto specifically calls out the values and principles of:

• Working software over comprehensive documentation.
• The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.
• Working software is the primary measure of progress.

That doesn't mean documentation is useless or unnecessary, but it very much changes the way agile projects implement it. While not spelled out in any particular framework, agile software development tends to integrate the following engineering practices in one form or another.

1. Self-descriptive software. This encompasses things like descriptive class and method names, the use of explaining variables, and other engineering techniques that reduce the need for explicit documentation outside of the code itself.
2. Comments that explain how or why code works. Good comments explain how to use a piece of code, or why it was designed in a particular way. Comments in modern codebases should never be used to cover up unintuitive names or paper over poor design, except as an interim step to refactoring.
3. Unit tests explain how code works. Your code base should be chock-full of unit tests that clearly describe the expected behavior and assumptions expressed in the code they're exercising.
4. Behavior-driven tests explain how your system works. A good BDD suite clearly expresses the assumptions and implementation details of your business logic in the same language as your business domain. "When I do X, the system should do Y" is properly embodied in executable tests that live alongside the code, not legacy stories or tickets from the early Triassic period.
5. Continuous integration increases system knowledge and reduces errors. Implementing CI doesn't just improve code quality. When properly done and with sufficient unit and system tests, CI creates a tight feedback loop that uncovers side-effects and regressions, and generally increases team knowledge of the overall system. Of course, going "green" with insufficient test coverage is largely useless, so this has to be combined with good coding and test development practices.
6. Documentation should be part of the codebase. Most modern languages and frameworks support some sort of embedded documentation (think RDoc or Swagger) that embeds documentation alongside the code it describes. While this sort of documentation can be missing or wrong, the fact that it lives in the codebase enables the team to maintain it as part of their development, testing, and debugging processes. This is in stark contrast to maintaining outdated specifications in a separate system.

Another way to think about this is that legacy specifications, acceptance criteria, and so forth are point-in-time statements that live outside the codebase. They exist to foster collaboration, but anything outside the codebase itself is really just an indirect proxy for a demonstrable system behavior. This is not only error-prone, but maintaining indirect or secondary documentation inevitably creates drag on the project.

Agile frameworks don't usually dictate engineering practices, so your team is free to implement the agile principles and values in other ways if they prefer. However, these things are considered best practices for a reason, so deviate from them at your own risk.

Answer 2

What you are describing appears to be the use of user stories as requirements in the ISO/IEC/IEEE 29148 sense.

Although it's not uncommon for people to consider the user story to be the "as a {role}, I want {goal} so that {objective}", that's just the card part of a user story. A user story is also a conversation between the team and stakeholders, which results in an understanding of what is necessary or expected. The conversation between the team and the stakeholders results in things like acceptance criteria, mockups and wireframes, and other notes that help guide the development. Finally, the user story includes confirmation that the objectives have been met. These are the Three Cs of User Stories.

The evolution of a user story from a card through the conversation through the confirmation mirrors the lifecycle of requirements from discovery through elicitation and then the use in design, construction, verification, and validation of the system described in standards such as ISO/IEC/IEEE 29148 and other more traditional descriptions of requirements engineering.

However, requirements management is also a part of requirements engineering. Requirements management is about making sure that each requirement, as well as the overall set of requirements, maintains the necessary state over time. In particular, individual requirements and the set of requirements are expected to be complete and consistent at every point in time.

The idea of updating user stories, their associated acceptance criteria, and any relevant test cases is a way to implement requirements management of user stories. If you have software source code (commits, pull requests) and test cases also linked to the user stories and acceptance criteria, you also satisfy the traceability aspects of requirements engineering.

In theory, there's nothing wrong with this approach. In some cases, it may even be desired or necessary to have a robust requirements engineering process. In reality, the problems that you present concerning having to search for the related user story (or stories) for updating can be painful. Some tools may make this easier, but it would require applying consistent metadata to issues.

For some systems, this approach may work fine. I'm looking primarily at bespoke software systems that are built for one specific client against a specification with a limited number of user roles where you'd have an easier time deconflicting requirements. In other cases, such as developing commercial software for the market where you are building to needs rather than to spec, it's much harder to manage. Many of the requirements engineering techniques that I've come across are better suited for building to spec rather than building for market needs.

When building systems for need, I tend to focus on the ability to generate an as-built specification rather than a to-build specification. Instead of specifying the requirements that must be satisfied, specify the behavior (functional) and quality attributes (non-functional) characteristics of the system. Tools that allow you to write BDD-style test cases offer a good way to generate these, especially for test cases at the system level. Managing the tests becomes more important than managing the requirements.

Answer 3

User Story is just a format, your question doesn't really relate to the format. But first - seems like different people use different terminology, so in scope of this answer:

• (Functional) Requirements - a description of how system should behave
• Requirement Document - contains summed up requirements for the product
• Task - a piece of requirements that needs to be implemented. Tasks show evolution of the product - how it's been developed. It's like a diff between 2 versions of Requirement Document.

User Story format can be used to describe any type of requirements - be it a Task or a Requirement Document. But it's just one of possible formats.

Your problem isn't really about User Story format. Rather it's about how to evolve tasks and when to close them, whether we should update tasks and re-open them after we changed our mind. To answer that:

1. Tasks exist to describe a piece of work to be done. After it's closed it means it accomplished its work and you should stop editing it.
2. If the task is closed and you changed your mind or came up with new ideas on that functionality - you create another task. Ideally - link them.
3. Requirement Document (if you decide to have one) is what needs to be updated as the ideas evolve.
4. There are 2 types of Requirement Documents: what needs to be done or what has been done. Both are valid approaches, different people choose different styles of work. You can even use both simultaneously.

Answer 4

User stories are a placeholder for the conversations people need to have to get a shared understanding on what needs to be built.

User stories are part of the documentation, but they are not documentation as you seem to be referring in your question (i.e. with a lot of details to make them, as you say, "complete").

You seem to be using the user stories as complete requirements, but they are just items in your backlog that tell you that you should develop something described very shortly by the user story title. Once you decide that you want to work on the user story, you need to discuss it. A bunch of items might be created during that conversation, like schematics, drawings, pictures, documentation, acceptance criteria, videos, etc, something that you can attach to the user story to later remember what people discussed, decided, and agreed upon, but even those things are not what you might call documentation in a traditional sense. It's just enough things to get the shared understanding and know what to build. The Agile manifesto says "Working software over comprehensive documentation".

Are user stories supposed to be used like this to document the system?

My answer is "no". User stories are A means to an end: to build the software.

They are called stories because you tell stories around them in order to build a shared understanding of what needs to be built so people work toward the same target. Requirements or documentation or specification, or whatever you want to call them contain written descriptions of what needs to be built. They are THE means to an end. To do this, they have to be complete, otherwise people need to start to use stories to fill in the gaps or update the requirements before making changes to the software (since the requirements describe what the software needs to do).

See also:

• In Scrum, are stories supposed to be a replacement for product requirements?
• User Stories Ain’t Requirements
• How to define complex business rules using User Stories?

Answer 5

For me, this seems to be the classic JIRA - Confluence case.

When you define your requirements in JIRA as user stories, your "Done" stories basically cease to exist to form a concise product specification. You can still look them up and update, but this is a nightmare, as described in the question.

For a way more practical solution, JIRA or a similar tool should only be used for managing the product backlog (title, estimation, value, order). User stories are not part of the product backlog, anyway. Specification, whether user stories or another format, should be somewhere else, e.g. Confluence, XWiki, Sharepoint. If there is a change to the requirements, a new product backlog item should be created and linked to the specification.

Bonus: unless you are working on something underwhelmingly simple, such as selling socks online, the classic user story template will hardly add value to the delivery process.