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.

Agile Testing - a response to The Golden Rules of Testing

Today someone sent me a link to a Software Test Professionals (STP) article on the Golden Rules of Testing as applied to an agile project. I'm pleased that the testing community is embracing agile more and trying to figure out how to fit in. However, I was troubled by some of the statements I read. It appears I'm the "that's not how we do it in agile" guy who has some objections to his views. Commenting on the article directly required giving my name, address, occupation etc which I was unwilling to do so I'm posting my comments here. Interestingly, the author wrote a post on his personal blog “Am I an agile tester?” that is much closer to the views that I hold.

Ray's words are in normal text below. My replies are italicized and in blue.
 
***************************

Switching from Waterfall to Agile is known to directly impact testers.

Yes. But not just testers - everyone.

It's true; the change can be difficult for some of us. However, fear not, some things never change regardless of the development approach.

Agreed.

I've put together what I think are the golden rules of testing that still apply. So when someone says "that's not how we do it in Agile" (and believe me - they will) don't take none of it and stick with the basics. 

<spidey senses tingling>Depending on how you interpret this statement, this is either ok, or a recipe for failure.</spidey senses tingling>

Read these simple golden rules for software testing based on my own experiences.

It’s all about finding the bug as early as possible:

Close. It is actually about preventing the defect from being found rather than finding it as early as possible. Finding it earlier is better, preventing it is best. For more on this topic, check out this fantastic go-to article on agile QA: http://bit.ly/aOfJM5

• Start the software testing process by analyzing requirements long before development. I object to the word “long” here. It implies that we do big requirements up front. It also more than implies a process smell - the long gap between anaylsis and implementation. Rather, let’s take a look at a story together as a team right before development begins on that story to analyze the requirements and create our tests before we start coding. Then, repeat for the next story.

Make sure you have these 3 software testing levels:

• Integration testing (performed by IT) performed by the team.
• System testing (performed by professional testers) performed by the team.
• Acceptance testing (performed by business users) performed by the team.

Don’t expect too much of automated testing:

• First let me state this: Automated testing can be extremely useful and can be a real time saver. But it can also turn out to be a very expensive and an invalid solution. I tried to find more some information from Ray on what he means by automated testing but couldn’t find any additional info despite the fact that he has written a few blog posts about automated testing. This statement is usually delivered by someone who has attempted and struggled with automated UI testing. Automated UI testing can be more difficult and more expensive, but I'm not sure how it is an "invalid solution". However, automated service testing is comparably simple, not expensive, not invalid, and a consistent time saver. Automated UI testing can still be valuable, but the ratio of service to UI tests should be heavily weighted toward service testing IMO.

Deal with resistance:

• If you like to be instantly popular, don’t become a software tester! You’ll find out that you are going to meet a great deal of resistance. It is very likely that you will end up being the sole defender of quality at a certain point. Other participants in the project will be tempted to go for the deadline, whatever the quality of the application is. This is one of the reasons the agile testing community preaches a whole team approach to quality. Being the sole defender of anything on a project is a problem. We want our teams to own the budget and schedule, not just the PM. We want our teams to own quality, not just the tester, etc.