Agile Documentation


After encountering teams that claimed to have disposed of all documentation when they adopted agile practices, Lisa Crispin decided to set the record straight on what the Agile Manifesto’s recommendation to value working software over documentation really means.

I often get questions about documentation in agile projects. Some people tell me their team “threw all the documentation out the window” when they started their “agile” transition. It puzzles me that some teams seize on agile as an excuse to not do documentation. Valuing working software over documentation, as stated in the Agile Manifesto, doesn't mean “throw out the documentation.” We still value documentation. The aim of agile development is to produce "just enough" documentation and keep it up to date and useful at all times. It has to work for the technical team and the business experts. 

We Need What We Need
Testers used to traditional phased-and-gated projects are nervous about losing detailed requirements documents and test plans. These things don’t go away, they just take different forms. Rather than Word documents that get out of date, we use wikis and other tools that facilitate collaboration and automated tests that are always up to date.

You need the documentation that you need. It's situation-dependent. I've worked on XP teams where our clients wanted a full complement of documentation—requirements docs, test plans, user manuals, design documents. We had tech writers on our teams to assist with these (which I highly recommend!). We kept things simple and made them work for us. For example, our requirements docs consisted of the user story, high level test cases, and mock-ups as applicable, and the clients were fine with that. For the test plan, we created a document that had information our team could use, such as release plans, names and contact information for everyone involved in the project, and what tests would be automated. Agile Testing, the book I co-wrote with Janet Gregory, includes a test plan templateto help teams create test plans that actually get used and provide value for their team. 

Documenting Early and Often
On my current team (which I've been on since 2003), documentation usually starts with mind maps, examples, and flow diagrams drawn on the whiteboard when we first discuss a new feature or theme. We take photos of these and post them on our wiki—not only for the benefit of remote team members but also to remind ourselves why we made certain decisions. For complex themes, we often create a wiki page on which team members brainstorm design ideas, raise issues, and ask questions. Wikis are a great collaboration tool, particularly if you have remote team members, as we do. A record of our discussions is also helpful later when we want to know how we arrived at a particular design. 

Once we’ve broken a theme down into small, incremental user stories and have begun to work on them, documentation continues with our product owner's (PO’s) conditions of satisfaction and mockups. Our PO has a “story checklist” template to help him think through what areas of the application and the business might be affected by the story. For example, will any reports be affected? He often includes some high-level test cases.

Collaborating Through Examples
We ask the customers for lots of concrete examples of desired and undesired behavior. Since ours is a financial services application, it works well for the PO to give us examples in spreadsheet form. Those are easy to turn into executable tests. Examples on whiteboards work well, too, since discussing a story around a whiteboard is a great way to collaborate.

Our team holds a one-hour “pre-planning” session a day or two before the start of the iteration. The PO goes through each story, and we ask questions. As a team, including all programmers and testers, we write requirements and high-level test cases on a whiteboard during sprint pre-planning and planning. That helps us share a common understanding of each story. Questions that the PO can’t answer right away are written on the board in a different color marker, so we can make sure to get the answers later. We take photos of this whiteboard, even though we also put the information in narrative form on the wiki.

When the iteration starts, we testers flesh out these examples and requirements on the team wiki, adding more information and examples, more detailed test cases, screenshots, mockups, and photos of whiteboard design drawings. For complex stories, we often mind map test cases and scenarios, which helps make sure we don’t miss anything important. We go over these test cases one more time with the PO—and sometimes with other stakeholders—to make sure we’ve understood all aspects of the story.

User Comments

1 comment
Seb Rose's picture
Seb Rose

To a large extent I agree with Keith (I also worked at Rational on the DOORS product), but... there is a big difference between executable documentation (such as FitNesse or Cucumber tests) and static documentation.

With the former, when the product deviates from the documentation (i.e. tests) the deviation is reported immediately through a failed test. The latter requires manual updating.

Some tools, such as DOORS, live somewhere in between. They have some ability to link from specification through to test results, using integrations with other tools. It feels (subjectively) like this is not as good as fully executable specifications - I'm not aware of any CI server with a DOORS plugin, for example - but a similar effect might be achieved.

June 23, 2011 - 5:54am

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.