Documentation and collaboration

To paraphrase Winston Churchill "Documentation is the worst form of communication available to you... except for all the others that have been tried".

One of the agile principles is "The most efficient and effective method of conveying information to and within a development team is face-to-face conversation". Conversation and close collaboration are fine on small projects with little novelty and little staff turnover. Let's assume that you use conversation and close collaboration. What do you do when you need to remind yourself of a decision that was taken a few weeks (or months, or even sometimes years) ago? How does conversation help that, unless you have recorded the conversation (and guess what, if it is written, that's a document, just one that is particularly hard to use). What if the best answer to "why are we doing that?" is "go ask Joe", with whom you had the conversation? Well, I have news for you, Joe left six months ago and now works for a competitor, so good luck with that, you had better hope that he documented something.

Communication through conversation is suitable for ephemeral information. If the information has a life, it needs to be recorded. If this is not done as a group activity, then each person on the team will make their own record, which will likely be incomplete and almost certainly inconsistent with the record of other people. Try this experiment next time you are in a meeting - get two people to take minutes (independently of each other) and compare afterwards what they have written.

So you need to record things, and the natural form of record is some form of document. The main problem with documents is not the documents per se, it is their use as if they were the product. They are not, they are just a (form of) repository. Ideally, as someone else has pointed out, the documents would just be reports. We use documents because they have structure, and that brings benefits, like making it easier to find things and also giving guidance about what needs to be considered by having sections calling out specific topics (what, it had to be secure? we never had a conversation about that!). By all means converse and collaborate closely, but record the results in a form that you can easily find them when you need them in the future (which you will, except for the most trivial systems).

The hatred of "big" requirements documents seems to me to largely stem from a post hoc ergo propter hoc logical fallacy - these failing projects had big requirements documents therefore big requirements documents caused the failure. Of course it is essential to document requirements, it is stunningly naive (but amazingly successful for methodologists on a personal basis) to think otherwise, though it does pander to the prejudices of developers. As I have said before, documenting requirements does not always or necessarily mean a requirements document. However, let's not forget the advantages of a document: amongst others, it gives us one place to find the requirements for the whole system, it gives us a great way of locating related (overlapping, duplicate or inconsistent) requirements, it gives us a basis for configuration management, it is very often needed for contractual reasons.

There is absolutely no reason why documents cannot be developed incrementally, filling in information as it is obtained. There is also absolutely no reason why sections (even line items) cannot be approved and acted upon independently. There is also absolutely no reason why every requirement has to be in one document, so long as people can find the information. In particular, it is extremely bad practice to place requirements from different levels (e.g. stakeholders and architects) in the same document. Likewise, why document the detail of all (sub-)systems in one document?

One final question - if documents are so bad, how come the form that most people choose to use to argue against them is ... documents? Surely they should just converse and closely collaborate with everyone else to get their points across?

Waitrose v Ocado, the Final

Last order, I searched for Special K and got an error page. Oh. Well, I know it is a cereal, so Cupboard -> Food -> Cereals. Even better, it's from Kelloggs, so let's click that button. Hmm, in all the four pages, the only Special K items are the cereal bars. OK, turn off Kellogg in the search. There it is - a pain to find because you can't enter a page number of use a binary search as you only get the closest pages to choose from. Let's order while I can. Hmm, only 500g packets, I'm sure they do a 750. Here's a thought, I see Corn Flakes here, surely the most iconic Kellogg product, not sure it was in the restricted list. Ah, it isn't.

So, site too hard to use, coded by script kiddies wanting to show off rather than people with the customers' interests at heart. Too many mistakes, too slow. I'm out of here.

Bye!

Waitrose v Ocado - which one is better - Part 3

Second order from Waitrose. First thing I notice is that my trolley has items in it. It is the last order I made. Interesting. There is an option to tick items and remove them. I guess this will be useful as more and more things become part of a regular order, but there tends to be a lot of variation week to week. This first time I deleted about half the items.
On checking out, the delivery address does not default to my address, even though that is the only one on record. You have to select to use it, then click the radio button next to it. I know it's only two clicks, but strangely irritating.
That time it took me nearly three quarters of an hour. Still slower than Ocado.

Waitrose v Ocado - which one is better - Part 2

Following on from Part 1, still on the same order. Some more points:

• The Waitrose site is much slower than Ocado's. Having pop-ups that dim the rest of the screen while updating, even if just to add an item, means I cannot do anything else while waiting. On Ocado, I can add items as fast as I can move the mouse and click. Clearly, Ocado's web developers have learnt to separate processing from handling the input queue, which is pretty basic stuff
• Waitrose has a forum, which is good, whereas Ocado only has email communication
• Both sites have far too many graphical adverts at the top, before I see what I really want.

Waitrose v Ocado - which one is better - Part 1

We have been long term users of Ocado's delivery service - over five years, I think. Now that Waitrose has decided to make delivery free for orders over £50, which is less than my normal delivery, and Ocado charges me around £10 a month for deliveries over £40 each, for I have decided to give Waitrose a try for a month and see what I think. I believe it will take that long to become sufficiently familiar with the Waitrose site as opposed to Ocado.

So far:

• Multiple search on Ocado is incredibly useful. I often start by putting in my shopping list, knowing that the categories can be sorted by Favourites first means that I usually see the things I want early
  
• Ability to edit Favourites on Ocado is very useful
• Suggested order from Ocado also very useful. I never order everything, but it is a great reminder.
• Browsing through by pressing "Next" button for next category very handy on Ocado, as opposed to going to the top of the page, clicking on a (not very obvious) drop-down menu in Waitrose.
• Ocado site looks like it was designed for usability, Waitrose looks like a web designer was showing off

So far (and this is only one order), Ocado is looking like it is in the lead. It took me nearly 45 minutes to place my first order on Waitrose, it normally takes well under 15 on Ocado. And that order was around half of the normal order value. That is at least two hours a month, and I think my time is worth more than £5 / hr.

Murdoch Maths?

The front page of the Sunday Times had a headline that police could be looking for 30,000 rioters. How did they get that figure? Simple, according to police, there were between 1,500 and 3,000 reported crimes during the riots and each crime has "up to" ten people involved. Therefore "up to" 30,000 rioters.

Am I the only one who can see the massive holes in that reasoning? If I were Ben Goldacre, I could probably spin this out to a full article, but I won't, I'll just leave it there.

Agile's four tenets - false dichotomies? (or Agile versus the traditionalists, part 2)

The Agile Manifesto has four tenets:

1. Individuals and interactions over processes and tools
2. Working software over comprehensive documentation
3. Customer collaboration over contract negotiation
4. Responding to change over following a plan

Are these four "X over Y" statements really putting things into opposition? I don't think so. Let's examine each and see.

Individuals and interactions over processes and tools: I don't think anyone would argue that individuals and interactions are unimportant. But does this really mean a choice? Of course not. What about tools that encourage interactions? We all want our development teams to have the best individuals in them, but it is a truism that 50% of developers are below average (almost, but not quite, by definition). So how do we make the best of these less than stellar individuals? Well, how about having a process in place that lets us check their work, and maybe even lets them learn. Hey, maybe we could pair them up with a more experienced (better?) developer? We could even give it a sexy name, maybe "pair-programming". (See what I did there - agile prefers individuals and interactions over processes and tools, and achieves this by, oh, having processes. Hmm.) And how do we get interactions? Maybe we could have a quick meeting every day, we'll make everyone stand up so it doesn't take too much time. Oh, another process. Well, how do we decide what to do? I know, we'll keep a list of things to do (what will we use to store this, I don't know, maybe some sort of todo list tool? Oh, look, a tool) and every so often we'll decide which are the most important. Oooh, another process. OK, scrap all that, let's just let everyone interact with everyone else. Let's see, we have ten developers on the team, that means forty-five communication channels. We can manage that. What happens when the project grows and we now need twenty developers? We now need 190 channels. Whoah, that's a lot. Maybe we should break things down into teams and get the teams to communicate through the team leads. Sounds like more of that darned process stuff.

Working software over comprehensive documentation: I think we can all agree that we want working software. This is a no-brainer, right? So, how do we know the software is working? How do we know it doesn't have some hidden flaw that's going to bring the whole thing crashing about our ears? We don't. Unless we test (actually, that's no guarantee, but that doesn't invalidate the argument here). What are we testing against? Well, we have these User Stories, and the software meets all of those. But does it also behave in the expected way when people do the wrong thing? OK, so we need to make sure that the User Stories account for user error (or missing input, or communication line corruption, or invalid data in the database, or...). Great, sorted that out. oh, just thought, what happens when it doesn't work? We'll need to look into the design to see how the story was implemented, and we will want to know why design choices were made so that we can decide if they are (still) valid. And we will also need to understand how the code matches the design. Ah, there is no comprehensive design documentation. OK, I'll just ask Joe, who coded it. Oh, Joe left six months ago and is now at a competitor. Hmm

Customer collaboration over contract negotiation: Hey, Mr. Customer, we've got a great idea! You just give us some money and we'll deliver what we can. And we'll keep chasing you for input. What, you want to know how much it will all cost so you can work out Return on Investment? No, you don't need that, we'll just keep spending your money until it's good enough. No, there's no need for a contract, you can trust us! No, wait, come back, it will work, honest, lots of people who make their money telling people how to do this say it will. OK, let's step back a little, we all know it isn't really like that (don't we?). But in the real world, customers do want to see some commitment. And, sad though it may be, they often want that commitment to be legally binding. And that means a contract, which needs to be negotiated. Yes, we would all like to be collaborators with our customers, and a good contract provides the legal framework for that to be possible.

Responding to change over following a plan: Change happens (to mis-quote Forrest Gump). A change is only a change if there is something there to be changed. What is that something? Well, a good start is what was planned to be produced. Actually, this tenet isn't as much of a false dichotomy as the others. In fact, it is one of the bases of good project management practice in all disciplines. But there must be some sort of plan, even though it is acknowledged that it will inevitably change.

So when we look at these "X over Y" statements, they either don't stand up to scrutiny as being in as much opposition as is claimed, or are what has been best practice for a long time. So what is agile giving us? Unfortunately (stand by for wild over-generalization), it is often used as an excuse for throwing out the "Y" parts of the tenets without considering the consequences. In many cases, it is little more than an excuse for undisciplined hacking of the worst sort. To reiterate a statement that I have made many times in the past, I am not against the ideas and ideals of agile. What I am against is people treating it as a panacea or something that blows away the need to remember the lessons of the past. So, perhaps you should prefer X over Y, but that does not mean that you don't do the Y at all.

Response to Sticky Minds article

I wrote this in response to an article on Agile Documentation on StickyMinds - it will make more sense if you read the article first (Agile Documentation).

(Truth in responding - I work for Rational and for many years was a DOORS Principal Consultant)
I wholeheartedly agree with the principles behind what you write here. A well-written requirements document is not just a 300-page lump of paper, it is structured to make things easy to find and with a narrative to make it easy to follow. Unfortunately, when writing specifications people forget everything they ever learnt about writing.
An advantage of a document over a Wiki is that it has that structure - so it becomes fairly easy to see where an area is noticeably heavier (or lighter) than others - particularly important when some areas have regulatory importance. Of course, a tool is even better - and there is no excuse for these things, whether in word processors or requirements tools, to be out of date. Even a simple system should be no harder to maintain than a Wiki. I get quite cross when I hear people say things like "you can't use DOORS for agile". Of course you can! It's just a repository, you can use it how you like.
I posted something on my internal IBM blog about (apparent) false dichotomies in the agile manifesto and have now added it here (scroll down to the section on Working software over comprehensive documentation)