Specific examples of Agile documentation? [closed]

Question

In an answer to the question Documents for a project?, Chris Ballance replied that "User Stories" and a "burndown chart" are the two most useful types of project documentation for a developer.

My question is, do you know of any good example[s], which I can see (for example on the internet, or in a book), of these kinds of documentation?

If possible I'd be happy to see many examples, including:

• Small/short/simple examples
• Big/long/complicated examples
• Famous examples
• High-quality examples

I don't find this an easy topic to Google for: I find lots written about it, but fewer demonstrations showing it.

Lekishalela

Answer 1

A very good place to start as far as books are concerned is User Stories Applied and Agile Estimation and Planning both by Mike Cohn. This have excellent examples and good starting points for anyone first coming to agile methodologies.

As far as website resources they are few and far between. Probably a good place to actually start would be searching for those keywords on Google Images as many people take photos of their burndown charts and User Stories. This helped me a lot when starting. Here are some samples: Burndown Chart, and User Stories

Please note however while a burndown chart is a simple report that you run on your current story points left in an iteration, User stories are more complex than that and do require a bit of reading to wrap your head around. Start with User Stories Applied book for that.

Hope that helps!

Nodal

I'm surprised to hear that "website resources are few and far between": are these types of documentation not used in practice, then, by "virtual teams" (i.e. by geographically distributed developers) developing open source (i.e. publicly available) projects? If not, can you speculate as to why not? – Lekishalela

I actually work on a remote agile team and of course we use remote tools, I thought you meant from an aspect of learning agile. For virtual tools you have options such as Acunote, TargetProcess, Unfuddle. These tools are useful for remote teams but should not replace a cork board when possible. – Nodal

So I think you're saying that user stories etc. are used by virtual teams; but, they tend not to be on web sites, because instead they're authored using tools [like the ones you cited] other than the web? – Lekishalela

Or, is it more to do with the difference between closed/proprietary and open/public development projects: i.e. that they are on web sites, but not on public web sites? – Lekishalela

Thanks for recommending Cohn's books, btw: the first one especially has favourable reviews on Amazon. – Lekishalela

I would say on our team we do have User stories however it's easy to make them too big and miss the point. Part of the reason of having the user stories on index cards is so you can't make the user stories too large. – Nodal

to answer your other question there, we use private websites that require authentication to gain access to the project details if thats what you mean. – Nodal

What I meant was that you had said, "website resources are few and far between", and I was wondering why that is, given that there are many public, open source projects on the net: maybe that implies that most of public, open source projects on the net don't use user stories and/or burndown charts. – Lekishalela

Mike Cohn's stuff is quality. – Compression

Answer 2

I think for both of these questions, you can do a lot worse than scan over Alistair Cockburn's web site. In particular, he has a great article about burndown charts and some different ways to generate them:

http://alistair.cockburn.us/Earned-value+and+burn+charts

(thoug I echo the earlier poster's recommendation of Mike Cohn's work).

One of the tricks is deciding what kind of documentation is good for YOUR project. Do you have many developers, spread over time and space? You will need bigger, heavier, more detailed stories. Do you have one or two devs working in the same place? You can get away with lighter ones. Has the team worked in the system (if it's legacy) for a long time? Light stories will probably do. Is the team new to the system, or are its business requirements complex? This pushes you in the more-detail direction.

If you're on a "small" project by any of the dozen definitions of small, you may be fine with very light stories. Here's an example, again from Cockburn's site:

http://alistair.cockburn.us/Examples+of+ultra-light+use+cases

Erlandson

Answer 3

A few months ago, we started writing the user documentation at the same time as we are developing features. A technical writer is assigned to each Scrum teams.

Having to write the user documentation while developing helps validating the design. The technical writer also participate in the design of the application.

This is in addition of release burndown and sprint burndown.

Additional documentation is created by the team when they feel it is useful to communicate with the product owner. This became less important as we are learning to write better user stories.

Untutored

I've always thought that a functional spec is the most useful documentation. The user documentation is a subclass of functional specification, IMO. So, if you're saying that the user documentation is sufficient, and that it's good to develop it before and/or with the software, I find that plausible. – Lekishalela

Actually, the user documentation might be enough for developers ("what end-user functionality are we building?") but might not be enoug for project managers ("what are doing in this sprint, and conversely what lower-priority functionality is triaged and being ignored at least until next time?"). – Lekishalela

Answer 4

Consider reading Ambler's "Agile Modeling". He makes a very strong case as to why just creating tons of full UMLs is a fairly bad idea, and gives some good examples.

Drandell

Merely explaining why not to create tons of UML wouldn't be an answer to my question. – Lekishalela

Sorry, I didn't have time to write anything more complete, mostly wanted to refer you to the book. He does discuss his alternatives to use cases and what would be important to capture. – Drandell