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.

  • Another key thing that you need to provide for is version control. Some systems such as Microsoft SharePoint provide document versioning automatically. Some word-processors provide revision tracking within a document. You can also improvise a filing system manually. In short, you need to be able to maintain changes to a document without losing track of how the document used to be. And, you need to be able to clearly identify exactly what changed from any one version to any other. Strangely, many commonly-used workload management systems do not provide for this, and I really don't under Sep 1, 2020 at 16:23

5 Answers 5



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.

  • 1
    My heart rate jumped as I was reading it. its essential of software development. if I could, I upvote it 10x. Nov 6, 2020 at 11:00

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.

  • How does this approach suggest describing something like a traditional task? E.g. you have original User Story that described the functionality, everything's implemented now. Then you decided to update 1 item out of 10 (you changed your mind about it) - how do you tell developers/testers which item changed if you "restart" full User Story? Aug 6, 2020 at 12:48
  • @StanislavBashkyrtsev It depends. Not all requirements can effectively be captured in a user story format. For others, you can treat a user story as a user requirement and each acceptance criteria as a software requirement and denote the status of each one, with a user requirement being satisfied when all linked software requirements are satisfied. An other option would be a Delta, which is commonly used in specifications as well - you specify the changes and anything not noted as changed should be the same.
    – Thomas Owens
    Aug 6, 2020 at 12:54
  • Hm.. 1st option looks similar to linking a Requirement Document to tasks. The 2nd seems problematic because sometimes we need to refactor requirements substantially, so a diff would include a lot of noise (from a developer perspective). But still it's an interesting idea. Though it requires hardworking BA/manager to support the docs in perfect shape all the time :) Aug 6, 2020 at 13:42
  • @StanislavBashkyrtsev Yes, it does require a lot of work, perhaps even more than the value in doing it. Just because you can doesn't mean you should, but it looks like the OP's organization is doing it. For most people, I'd suggest looking at other ways of dealing with things, rather than trying to treat user stories as formal requirements and putting them through a requirements engineering process.
    – Thomas Owens
    Aug 6, 2020 at 13:57
  • @StanislavBashkyrtsev You asked, "[H]ow do you tell developers/testers which item changed if you 'restart' [the] full User Story?" You don't. Best practice is to treat all changes as new work, and re-plan and re-estimate all the new work from the current state of the project. User stories shouldn't carry historical context or legacy effort (e.g. consumed story points) around with them, especially in frameworks like Scrum or SAFe.
    – Todd A. Jacobs
    Sep 5, 2020 at 16:08

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.

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:

  • 1
    I'm not sure who wrote the Construx article "User Stories Ain't Requirements", since it's not attributed to an individual, but on June 1, 2020, Earl Beede gave a live talk titled "A User Story Can Be a Requirement", which together with my experiences with Agile in regulated industries forms the basis of my answer. User stories can be requirements if they are treated appropriately. The real question is if it makes sense to treat them as requirements.
    – Thomas Owens
    Aug 6, 2020 at 10:29
  • 2
    @ThomasOwens: It's clear from the question (or for me at least) that the way stories are used in the OPs team is like a requirements document. In blunt terms, like a Word document that needs to be consistent with what the application does. From here the described need to re-open user stories and update them with new features and requirements as things evolve. User stories are not complete requirements and not complete documentation, so, to the OP's question of Are user stories supposed to be used like this to document the system?, the answer is still "no". That's not how stories are used.
    – Bogdan
    Aug 6, 2020 at 12:14
  • Unfortunately, the video is no longer available (except maybe to paying Construx members), but that is wrong. User stories can be complete requirements and can be managed in the same way as traditional requirements. However, that doesn't mean that they should be - that is context-sensitive. It may not be how user stories are commonly used, but they can be used that way.
    – Thomas Owens
    Aug 6, 2020 at 12:23
  • @ThomasOwens: I understand what you're saying, but I still disagree :). User stories are A MEANS TO AN END. That end is "working software". You will then ask for feedback on the software and you will make changes to the software (using stories and what not as a means once again). You don't ask for feedback on the stories and go back and change the stories. Requirements (and to combine it then with a stronger word: specifications) are THE MEANS TO AN END. You're in this case not allowed to change the software until you change the requirements that tell you what to change in the software
    – Bogdan
    Aug 6, 2020 at 12:44
  • You have a user story and create software. You get feedback on the software and learn more. You then revise the user stories and then update the software to match such that every user story and its acceptance criteria are valid. No one is asking for feedback on the stories, but the stories and their acceptance criteria can be documentation of what the system can do. All you need to do is track the state of the user story and its acceptance criteria to know if it's new, changed yet not implemented, implemented, delivered, and so on.
    – Thomas Owens
    Aug 6, 2020 at 12:49

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.

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.