5

You can't just have user stories somehow the functionality of the program has to be documented. Do you end up with a specifications document with scrum? If you do do you end up assigning time to do this onto the task?

An example would be a complex workflow.
Another example would be a new member who comes onto the team.

1

10 Answers 10

3

There will be plenty of good ideas added to this question. My personal experience has taught me that:

1~ The working product is a form of documentation itself: assuming the product is accepted, then asking what it should do under certain condition is equivalent to asking what does it actually do under those conditions - log in and try it to get your answer.

2~ The tests, be them manual or automated (or a mix), are a form of documentation. Certainly unit tests may be way too far from the domain language spoken by the less-technically inclined team members (eg: 'business Experts', or Customers). Acceptance tests may be closer to a 'middle ground' of sort. Definitely BDD-style tests seem to have the best chance to build a ubiquitous language everyone can understand (see in this regard Gojko's Bridging the Communication Gap). Nonetheless, all of these form of tests are a form of documentation which can be used to determine what the product should do.

3~ Depending on where your project falls on the spectrum, your documentation (and, in general, all your ancillary artifacts) may require a higher or lower degree of ceremony. Smaller products, smaller teams, where time to market is critical may find that a very formal documentation of requirement costs way too much compared to the value it adds. Extremely large projects, spanning multiple teams and years of development, on the other hand, will find the ROI of formal documentation quite different.

4~ In the perfect world, we probably wouldn't need to document requirements other than in the form of working code (which, in the ivory Tower would also be self-explanatory) and tests (mostly for regression testing, and -on the fringe- to drive development of new features). Thus, the question of requirements documentation is a question about what's different between the Perfect World/Ivory Tower and the Real World/Trenches. The answer, of course, is different on a case-by-case, depending on the project and the team. For instance, we could say "All requirements shall be kept into this wiki, and maintained with the utmost care, etc etc..." but if the team is not familiar and comfortable with wikis this would not work.

5~ In the end, the stakeholders are those you should ask. Certainly, the topic should be approached in a collaborative manner, because everyone on the team will have to interact with the requirements throughout the project, but you must find a form of documentation that satisfy the stakeholders' needs.

All that being said, here's some places I've seen requirements documented while applying Scrum (why do I feel like this word should always be followed by an asterisk?):

  • PDF document
  • Bulletin Boards
  • Wiki
  • Wiki + Automated Acceptance Tests (read: FitNesse)
  • Unit tests
  • Manual Test Plans
  • User Stories, Use Cases diagrams (read: Enterprise Architect models)
  • Whiteboards around the office
  • Emails
  • Post-it notes

And, to be honest, I cannot say that any one system has a consistently higher correlation with a successful project than the others. I guess, indeed, we don't have a silver bullet.

HTH, thanks for the thought-provoking question!

2

Adding "documentation" as a task on each user story could certainly go a long ways towards your goal.

2

Scrum says you should document what you need, when you need it; it doesnt say you shouldnt have documents.

So if a document is required either by the finished product (eg. help documentation) or to produce the finished product (eg. requirements documentation) then there should be a documentation task/user story in your product backlog.

Appropriate priority should then be placed for that task.

For documentation the key point is;

  • Document only what you need, only when you need it.
2

You can't just have user stories somehow the functionality of the program has to be documented. Do you end up with a specifications document with scrum? If you do do you end up assigning time to do this onto the task?

Why can't you just have user stories? What purpose do these specification documents serve? What value does the investment in producing these documents return? Does the benefit out weigh the cost? If not, then isn't the time spent creating, and more importantly maintaining, these documents waste?

I know I'm asking more questions than providing answers, but I think part of what Scrum and other Agile approaches like lean do is force you to re-examine your current practices and see if they still make sense.

In the case of specifications, who will be updating and maintaining these documents once the feature has launched? In most companies I've been at, the documentation has been sparse, out of date, or rarely referenced.

Instead, why not use executable tests or BDD so that the documentation becomes part of the code and is executable. For example, see Ben Mabey's talk on Cucumber

If for some reason, a specific type of document is required for legal compliance purposes, you can always add it to the teams' definition of "done", however, I've found in most cases, stories and tests are more than sufficient forms of documentation.

1

Maybe my understanding of the question is completely wrong, but I what I understood was that the OP was uncomfortable with the mismatch between user stories and requirements. With reason I'd say.

In my opinion, user stories tell how a chunk of functionality shall be demonstrated to the product owner. The language of the story can be something that can be understood by the product owner but mainly by the developers. You might have stories that describe things that are not even directly required by the owner, but are breakdowns of things that are.

Requirements in the other hand are a detailed specification in domain user's language of what the system needs to do in order to be valid. In many cases a requirements document is not optional (fixed price projects for example).

What I do is a mix of both. I have a requirements document, and in most of my scrum stories, I have something in my notes that link that story with one or more items of the requirements. It is as simple as "See FR-042 and FR-45" (FR for functional requirement for example)

1

I think you are asking for a few different things here. If you are adding a new team member, then the documentation for the system should be geared toward their role on the team as part of the on-boarding process.

If you are talking about documenting the system functionality; in our organization our training teams document the functionality as part of the release. They are engaged (as a stakeholder) during the Sprint Review (demo) and then provided a training environment with the new functionality to prepare the training materials prior to release.

If you are talking about providing documentation for tractability, your backlog can serve as that with the proper process & controls added.

Each one of these different items takes planning and deliberate process development to effectively function and meet the needs of the team. We have included each one of these items in our retrospectives as an issue was identified and then developed our processes over time.

0

In addition to what James Kolpack said, the user story map should persist after the project is finished as it too is a form of documentation. I believe we plan to some how convert it to a document that lives in our Wiki when all is said and done.

The idea is that this document will be useful for people who need to maintain the system or add enhancements to it in the future because they will have an understanding of the user's perspective.

0

I mostly agree with Todd, but there was times when part of my team's task was to produce documentation : Documentation was the user story itself our PO asked to be delivered.

In these cases we followed the following guidelines:

  • try as much as we can to extract documentation from actual working code (typically some document generation program that read internal data structures or configuration files used both for building the actual program and build documents).
  • define in the documentation US the goal of the documentation :
    • who the reader is supposed to be
    • what he should be able to achieve reading that document.

In my experience that makes documents easier to write and enable some kind of test (you ask to someone, typically PO, to read the doc and say if it's OK considering the goal).

0

You write documentations to validate your system. User stories serve the same purpose if written correctly in a format that reflects user interaction with the system. I will recommend using BDD and writing stories using Gherkin syntax. Eventually your scenarios become your acceptance criteria which helps in validation whether the system is working correctly or not.

0

We have a docs team that produce the "instruction manual" for our product. The manual is structured around the main features of the product, and the tasks that the user can perform in those features.

Each sprint, Scrum teams work on user stories that add functionality to the product features.

After sprint planning, the docs team meet with the Scrum team and see which user stories that will be developed this sprint. The docs team then start enhancing the instruction manual by writing the initial docs. During the sprint, the docs team follow the progress of the user stories, and can use the product as it's deployed to test environments. At the end of the sprint, the docs team finialise the updated instruction manual and add final screen shots etc...

The instruction manual ship as part of the release each sprint.

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