A manual

Not having written a handbook or educational material for many years, starting up with a manual was hard. My final effort at my current position will be giving ground for a user manual.

But my first question was: which space does user documentation have during an agile project, for example if you're using scrum?

I believe it is important to include the people formulating the user manual in the team and the user manual should be part of the iteration increment. And the reason is this:

1. You have failed a product increment if there is no useable software delivered.
2. You have failed a product increment if the result cannot be used by the users.

And how can the users find the new stuff and how do they know how to use it without documentation. Of course you have the delivery notes but should a user collect all the delivery notes and try to find their way?

I'm currently thinking about the best form for a user manual in an agile project. One solution is of course a wiki: just add new pages and specify which version this applies to. Or something. But how does this work in an offline setting? For example, technicians in the fields. And not everyone loves reading on the screen: they like something to hold. Otherwise there wouldn't be so many books on for example Microsoft Word. As with everything else in an agile project you need to go back to the users and their user stories: which process do they want to follow when they get updated or learn about the application?

So, I'll be doing a classic Microsoft Word document with pictures and lists. And I'll continue thinking about how to deliver user manuals in agile projects.

How big are your stories?

The answer to that question is that depends. And it depends on what you are using them for. Stories that are far in the future is written to give people an idea of which stuff will be done "sometimes, but not now". These stories can be very big since if you're not going to build it, you don't know the details. That is self explaining: why would I want to know the details about stuff we're not building? But then you could say that sales people need details to be able to know which customers to target. But that problem should probably not be addressed by the product backlog, but the business plan. If you've targeted a specific client who have a specific need: simply write down on the product backlog item to take that customer into account when you're specify the details.

When you get closer in time: you break down the story into smaller stories, which can be handled and prioritized. Divide stories after the following principle:
* They can be prioritized independently - that is - they all have their own busines value
* If they are up for building in the near future, never make them larger than 1/3 of a sprint, so you don't risk having to finish a sprint without any completed stories
* Make them possible to build independently. If they are all connected and must be built at the same time, the previous advice is of no use.
* Don't divide the stories yourself: this is what you have story writing sessions for. Because only developers know which things can built independently and only the users know what has its own business value

Is everything on the product backlog a story?

Well, that depends... The reason you have the product backlog is that stakeholders have something to prioritize and so stakeholders get a rough sense when stuff will be available in a release.

The reason you have stories on the product backlog is that the format allows non developers to understand which user needs will be addressed. We specify who, what and why.

So to be able to answer the question if everything is a story, you need to ask yourself if everything you want to build can be expressed in that way. Of course, everything can be expressed in that manor, but sometimes it makes it just harder to read.

For example, the users wanted to switch columns in a grid. Well, of course you could write that as a story but as both developers and user understood "Change column order in usage quantity grid", why applying a format which in that case does not add to the readability.

It is often the same with defects or bugs or what ever you want to call it. I'm later going into the question if you should have bugs on your backlog (well, of course you shouldn't have defects in your system but you shouldn't have eaten that last sandwich either...) but if you do have bugs or defects on your backlog, writing them as stories probably just decreases the readability. The user knows (if they've experienced the problem) know what problem they want to be fixed.

And then there is all the other stuff. Like upgrading the test or development environment. Here I suggest a hybrid: for techie stuff: always include the why. Like for instance upgrading to SQL Server 2008: why should we do that? Otherwise non techies cannot see the benefit and therefor not rank it.

Where are the details in the story?

When I read a story to my son, I don't have to tell him all the details because he uses his imagination to fill in the blanks. And the amazing thing is that the details are just magnificent. Some of us oldies have the same objections to Lego. When we were kids there weren't all of those special parts but you could use your imagination to make those standard parts all the cool stuff we wanted to create or simply play with.

Working with stories like "As a mobile client user, I can book my assignments so that I don't get double booked" is some what like working with standard Lego. Mike Cohn says that a story is a placeholder for a conversation because if you drop a story like that on a bunch of developers and then run as fast as you can from the project, of course you won't get what you want. Just like dropping a handful of Lego parts on a kid and expecting him to build what you want, without direction.

So, a story needs to be completed with some direction. And this in the form of a conversation. If you're building a puzzle or completing some kind of model or Lego structure right from the box: what do you do? Well, most of us look at the completed picture to know what we're aiming for. OK: we're building a space ship. Cool!

Why do Lego use pictures as instructions? Just imagine building a Lego Space ship from a written description. How good are your chances at getting that right? And how much time is spent on trying to understand the text?

When you write the story: you draw the big picture and then you go in to details. Well, We're going to need some landing gear. And then we can get into all those details for that part. So, keep the story short and add details as you go along. When you need them. And when you have enough to make a decision.

But does that not mean that I have to be around those dev guys all the time? well, not all the time, but a lot of your time. If you are the one who can make decisions. For developers make those decisions if you're not there. Or they stop working.

But how can you estimate that story stuff? Sounds crazy. Well, back to my Lego. How long does it take to build that space ship? Well, even if you have the detailed spec and read from that and then give an estimate on how much time you will probably be wrong. And if you have kids, they will disturb you or wreck the stuff while you are working.

But what you can do is that you can take two lego models, look at them and say which one will take longer to build. You can probably say if one is double the effort. But if the model is huge (full size Cottage) you have no idea for it's is simply to big to estimate. And this is why you don't estimate stuff on the product backlog using actual (or as I call it: inaccurate) time but using story points. She's just getting more and more vague? Or... Get back to you!