Agile Development, Documentation and Bringing Projects back from the Dead

Dietrich Kappe, Friday, January 25, 2008 @ 5:19 am

One of the things that comes up quite frequently when talking about Agile development with newcomers to the topic, is the subject of documentation. They hear about "just enough" documentation, "low ceremony" process, and Wikis. To many it seems like "not enough" documentation.

When pressed on what they mean by documentation, they usually respond that what they want is a document that represents all of the specifications and decisions about specifications, the architecture, the design, and the tests that completely describe the system being developed. That may seem like a reasonable request, and I think that a typical agile project, with it's User Stories and various other Wiki artifacts that are produced in each sprint, constitute just such a record.

This still leaves some people cold. "I don't want people
hunting through the Wiki, I want a document I can hand someone and that
provides them with all they need to know." First, a Wiki allows you to
give more than one view into the documentation. You can organized pages
by sprint, or by feature, or what have you. Second, who is this
"someone" you will be handing this document to and what are they
supposed to do with the information after they read it?

Is the
"someone" a developer? A business person? An investor? A user interface
specialist? Are they supposed to make investment decisions? Technical
judgements? User interface decisions with it? Is it for training
purposes? Each of these audiences needs different documentation. One
size does not fit all.

"Well, what if I lose a developer? How
will I get them up to speed?" First, pair programming is far better at
mitigating the risk of losing one or more developers from your project.
You don't develop knowledge silos; everyone knows something about every
part of the system. Second, pair programming is also far better at
bringing a new developer up to speed. With pair programming, I can have
a developer being somewhat productive after only one week. With onesy
programming, the standard is to have the developer be fully effective
working on their own. That can take the newby and an experienced team
member in the role of trainer over three months to accomplish on a
typical project.

"Well, what if I lose all of my developers and have to start over?"

You're
screwed. I have never seen or heard of a software project where this
was done successfully. An old system refactored? Yes. But development
restarted in any significant way? No. Writing such documentation for a
future team of developers is like mailing someone an out-of-date
textbook on quantum physics and saying, "good luck!!"

So the next time you call for documentation, make sure you know:

1. Who is your audience?
2. What they are supposed to do with the documentation?

If noone is using documentation like that now, it is unlikely someone else is going to find it useful in the future.

Technorati Tags: agile development, documentation

agile ajax

Comments

• Leave a comment
• Comment feed for this post
• TrackBack URL

None so far.

Leave a comment