Agile Chartering - an Agile Documentation Alternative

Last spring I wrote two posts about agile documentation (Part 1: Introduction and Part 2: Guiding Questions) and asked you to consider this statement: 

"A document isn’t the only vehicle for expressing or transferring good thinking and ideas."

Recently I coached a team that was converting an application from VB6 to VB.Net. One of the challenges of the project was to agree upon and define the rules for when to fix the old code, when to just get it working, when to re-write whole sections, etc. One method to gain agreement on this approach could be to schedule a series of meetings and write up the conversion rules and strategies in the project charter document. Here is what we did instead:

Using a variation of the silent brainstorming technique we spent about 20 minutes creating a light weight conversion manifesto we could all agree upon. As you can see, we had some fun when we named the groups. The manifesto was 'documented' using an easel pad, post-its and sharpies. We placed it on the wall in the team room and referenced it often throughout the project. Situations we could not have documented up front surfaced during the project and were discussed quickly while referencing the post-its. This light weight manifesto served as a great vehicle for expressing our good thinking and ideas.

A meeting and a word document could have accomplished this as well, but not in the same amount of time, with the same effectiveness, or with the same mirth. In addition this is a great team building experience for teams that already have enough experience with long meetings and longer documents.

For more ideas on how to streamline your project chartering, take a look at this new book by Diana Larsen and Ainsley Nies: Liftoff: Launching Agile Teams and Projects

---

FYI - here is a quick explanation of the manifesto:

Image Via ThunderBoxRoad.com

"Hold your nose, just get it working!": Yes, the existing legacy code isn't beautiful, but it works and the users are happy with the functionality. We focused on delivering the functionality as is without any modifications unless absolutely necessary. (see “If you have to pass gas, fess up”). This included ignoring existing known issues and defects.

"If you have to pass gas, fess up": In the rare occasion that code or design must be changed, you must discuss and gain agreement with the team before doing so. Any issues or resolutions that come up must be shared with the team.

“Don’t paint the outhouse”: We are going to be making changes to the application after we deploy the .Net version so there is no need for a fresh coat of paint at this time. No UI "clean-up" is allowed except for minor formatting issues and we won't do any re-factoring unless absolutely necessary.

“You can’t get out of the mob unless you get out of the city”: We used VB Migration partner to do the initial conversion to VB.Net. The tool was a big help to speed up the project but some of the converted code is a little ugly and the team wanted to dive in and fix it all right away. If we were to focus on fixing the ugly code now it would not deliver value to the user – just less ugly code. So we put our focus first on converting the code and getting it live (i.e. getting out of the city) so that we could leave the mob behind in later projects as we replaced parts of the system.

Subscribe to Winnipeg Agilist by Email

Agile Documentation – Part II: Guiding Questions

In Part I of this topic I asked you to consider how and why you currently use documentation and posed some questions for you to consider as you think about the place documentation may or may not have on your project. In this post I will list some additional guiding questions that I have found helpful when deciding on the level of documentation to include in a project.

While it is true that agile projects often produce less documentation, some documentation is still useful in order to communicate project scope, progress, and ideas. However, teams are asked to embrace some additional realities:

• We rarely know everything up front and that producing high quality documentation about requirements or design that may not be implemented is wasteful.
• A document isn’t the only vehicle for expressing or transferring good thinking and ideas

The tension between creating just enough documentation and too much documentation is part of the discipline that is needed for agile team members. Here are a few things to consider before your start writing that document:

1. Is this document for internal team use only? (example, for hand-off from one person to another) If so…
Can you communicate the information through a conversation instead?
Can you communicate the information through code instead?
Can you communicate through a drawing, picture, or other lite weight model instead?
If the answer is no to the questions above, what is the minimum amount of information you can capture in the document that would serve as a reminder for a future conversation?

2. Is the document for now or later?
If the document is required now, consider simplifying or replacing with a conversation, white board pictures, paper prototypes, code snippets, or brief videos summarizing decisions. If the document is for later (ex. Help Documents, regulatory documents, etc), then consider creating it later or adding it to your done criteria for each item in your backlog. Documents for ‘later’ do not need to be created up front but can be continually updated throughout the project. If the document is for later, how often do people actually use it?

3. Who is the audience for this documentation?
Ask your audience about the minimum set of information they require.

4. What is the business value of this documentation?
If it has little value, then it doesn’t need a lot of information. If it has a lot of value (like a required regulatory document), then make sure the level of detail accomplishes the required value and no more. Why are we producing this document? Would you pay someone to create this document? Is it worth the investment?

5. Is this information available through another means?
Instead of creating API documentation or SOA documentation, consider using one of the many tools available to generate your documentation. Instead of asking someone to read a design document, ask them to read and run your tests.

6. Does this document specify requirements or design in detail?
Since requirements change on our projects, capturing this level of detail up front may not be providing value to the project.

7. How often have I had to change this document in the past?
This is often a clue that your document contains too much detail.

8. Can I specify this information through an automated test instead?
Specification by Example (also known as ATDD or BDD) promotes writing your requirements as automated test cases (examples) instead of requirements bullets. This allows you to have an executable yet readable specification that is developed throughout the project in cooperation with your client and the development team. Test Driven Development is a technical practice that developers can use to write unit tests that describe and validate their code and design. This practice has lots of advantages, but one of the side effects is that the unit tests specify how and why the code works so that future developers viewing this code can understand this information without having to rely on out of date documentation.

9. How should I create the content for this document?
Consider creating the content using inclusive models. Inclusive models allow others to easily contribute as active participants in creating the content of the document and often involve paper, post-its, and whiteboards. A 35 page word document draft is not an inclusive model - you are more likely to get grammar and formatting edits than suggestions for improving or even re-doing the content.

10. Is this document so big that no one will read it?
“An attempt to avoid this ambiguity by writing everything down often leads to a document of the type Winston Churchill was working on before he was Prime Minister.  Mr. Churchill described it as follows: ‘this document, by its very size, ensures that it will never be read.’”- Allan Shalloway in “The Role of Quality Assurance in Lean-Agile”

For additional reading on this topic, take a look at the following links:

• http://www.agilemodeling.com/essays/agileDocumentation.htm/
• http://tynerblain.com/blog//2010/11/16/agile-documentation/
• http://watirmelon.files.wordpress.com/2011/05/specificationbyexamplealovestory.pdf

Agile Documentation - Part I

Agile Documentation. These two simple words represent a common question and concern for professionals who are new to agile. Many IT professionals who work in traditional environments are accustomed to spending a lot of their time carefully crafting documents to support the planning, requirements, and design of their project. They are often measured and compensated by their abilities to communicate ideas through documentation. After spending much of their career perfecting their communication skills through MS Word, Visio and MS Project, it is natural for them to wonder how projects can be successful without significant investment in documentation. Since one of the common early misconceptions about agile development is that documentation is no longer needed, you can understand how agile adoption would cause them to be concerned about both their careers and their projects.

For those who share this concern, let’s start by considering the following quote from Jeff Patton:

“Documents we write communicate our good thinking. You can write one without thinking. You can communicate good ideas without a document.” – Jeff Patton (Jan. 19, 2011 - twitter)

Before you sit down to write your next document, ask yourself these two questions:

1. Do I use the process of creating a document as a vehicle for good thinking? If so, what other ways could be used as a vehicle for good thinking?

2. Do I use documentation as a means of storing and then transferring good ideas to other team members (current and future)? If so, what other ways could be used to store and transfer those ideas?

In part II I’ll talk about some additional guiding questions and suggestions to help you make decisions on when and how to use documentation in agile projects. Before you read that post, please consider Jeff’s words and the questions above as you think about the place documentation may or may not have on your project.