A misconception among some developers is that Agile Development discourages documentation.
That?s
not true. Documentation is essential for the health of a project. Without documentation,
it?s hard (and
some time impossible) to figure out missing pieces; it?s hard to pick up someone else?s
work and move
forward. This someone else may be yourself, at times, after a few weeks of vacation
or when you return
to parts of your application after several months.
But, how do we create documentation? We certainly don?t want to get bogged down creating
and
maintaining documentation?you don?t want it to become ceremonial. Further documentation
has to
evolve as your project evolves. If it gets hard to keep up, you either give up and
end up with out of
date documentation.
How can we create a documentation that actually works? Let me discuss this with a recent experience.
A developer had researched how to implement certain functionality. It required using
a tool, creating a
couple of applications that utilized the output of the tool. He did a demo to the
team and showed how
things worked. He was asked to document his work before he left the project?and so
he did. He left
behind a textual document explaining step by step what tools to use, how to run them,
and the results to
expect.
Months later another developer picked up from where things were left. He tried to
integrate the sample
into the main application. It didn?t work. He found the documentation and tried to
follow it step by step.
That didn?t work either. After a few days of struggle, the developer asked me to help
figure out what?s
wrong. I went through the documentation. While I understood in general what was going
on, there were
a number of things that were not clear. What if the documentation is not right? What
if there are some
instructions missing from it? It was frustrating to put all pieces together and figure
out how all this was
supposed to work. After some struggle, we decided to started from the scratch, did
quite a bit of reading,
pulling some pointers from the broken documentation. It took both of us almost a day
to get this working.
We learnt quite a bit technically that day. But that was not it.
At the end of the day, now that things were working, we decided it is important to
document what we
have done. But, there was documentation to start with and that did not help! So, there
is no point
creating yet another similar documentation.
We decided that we will create an executable documentation (ED). We started building
a script. Line by
line, as we create the script, we gave names for parameters and output files that
were meaningful, and
executed the script to make sure it worked. We made the script change directories
where needed to run
programs from other subdirectories. As part of our ED, we wrote command to cleanup
the example, so
you can start over and see how things worked. We checked in, into subversion, the
code plus the ED.
Now, we have a documentation that not only can be read, but it can be executed as
well. Anyone can
run it and see it in action.
Agile Development is not about avoiding documentation. It is about creating documentation
that actually
works, one that helps you get your work done. Next time when your boss asks you to
document, don?t
say no, instead, create a working executable documentation.
