August 1, 2008

I was having lunch with a friend and she said her company was doing “agile”. I asked her to explain. She shrugged her shoulders and said “We don’t write documents.”

Ouch. Oh, don’t get me started.

It was a nice 2-hour lunch because of the ensuing conversation between friends.

We’ve all grown up in a time where our assignment was to write a glorious thick document (detail design document, requirements spec, etc.), that was never read. I’m as guilty as the rest. I once assigned a senior engineer the task of developing a detailed design for the user interface of a new product. He had built a wonderful 2-inch thick detailed design describing in detail the classes and interactions he would be using. The review was scheduled for 3 hours. It lasted 10 minutes. Why? No one had read it. Not even me. Ouch. The only feedback received was that on page 3 there was a long rambling sentence and wouldn’t it be better if it was split into 2 sentences. I’m not kidding. Tom, if you are still out there, I apologize. That 2 months could have been used writing code.

Ever since that experience I have challenged myself and my teams to develop minimal documentation, but documentation that really matters. One example is the Key Design Idea (KDI). KDIs are a high-level conceptual design, typically described pictorially with labels and a few sentences. Running a project usually results in 3 or 4 KDIs developed to capture the salient design aspects. A KDI can be developed usually within 1 day.

Agile Methods certainly de-emphasize the writing of documents. As a matter of fact, the original Agile Manifesto states: “We value working software over comprehensive documentation”. The great thing about agile is that you don’t write documents for documentation or process sake.

Agile helps you to think of documents as a result of an agile activity (as opposed to an assigned deliverable). For example, as you are writing code your design firms up. There is an important new aspect of your design emerging. You need to capture it in a KDI. Another example is holding a User Story workshop. Participants collaboratively brainstorm the requirements. As requirements are identified, they are written on index cards. The result of the workshop is a collection of user story cards – a “minimal document” of the agile activity. Yes, the stack of cards is the document! Another wonderful example of a document is a drawing on a whiteboard showing an architectural layering of your system. Take a digital photo of the drawing and put it on the server in the Designs folder. I’m not kidding – it is a document.

Examples of documents in an agile world include: user story cards, use cases, KDIs, product backlogs, iteration backlogs, overall release plan, reflection meeting findings, wiki pages, etc. Even the Kanban board with attached story cards under columns for “done”, “in work”, and “not started” is an example of an agile document!

Does that sound like “We don’t write documents?” No way.

Agile puts it in a different perspective – documents are minimal and meaningful – as they should be. They are a natural output of the agile practices. They are supportive in nature to writing code.

Compare this to the old-fashioned ways of developing software where the deliverable assignment was a document. Do you see the difference?

I still paid for lunch, but she will pay next time!

Comments? Feel Free! Contact me and let me know what you think.

Back to Blogs