Win a copy of Mesos in Action this week in the Cloud/Virtualizaton forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Documentation in Agile

 
Christophe Verré
Sheriff
Posts: 14691
16
Eclipse IDE Ubuntu VI Editor
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Is it true that very little documentation is produced in Agile ? What about testing documents ? Does it mean that there is no testing documents either ? Everything is decided between the testing team, the coding team, and maybe some others, and put into action by the testing team. Or does the testing team still has to make loads of printable/readable test cases ?
 
James Shore
author
Ranch Hand
Posts: 46
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Christophe,

Think of documents as a form of communication. Now compare them to other forms of communication, such as speaking face-to-face at a whiteboard, or over email, or by phone. What are their strengths? What are their weaknesses?

Now consider that a perfectly-executed agile method is going to put all of the key players in the same room full-time for the length of the project. All communication can be accomplished with face-to-face conversation at a whiteboard.

In this environment, what project communication is still best done with documents? Those are the documents you create in an agile project.

(Or you could just read the "documentation" section of our book. For a discussion of how testing works specifically, see my earlier post.)
[ November 02, 2007: Message edited by: James Shore ]
 
Christophe Verré
Sheriff
Posts: 14691
16
Eclipse IDE Ubuntu VI Editor
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thank you
 
Stan James
(instanceof Sidekick)
Ranch Hand
Posts: 8791
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Agile methods require very little documentation, but allow any other documentation you find necessary. If a stakeholder wants a doc from you, an Agile method would never forbid you to write it. You should have a conversation about the best communication medium to make sure a document is it. And some would suggest you ask the customer to schedule a story to write the document, just to show it isn't free.

I see this as part of "people over process." Talk to people. Don't make a doc just because the process says to when you know nobody will really read it.
 
Christophe Verré
Sheriff
Posts: 14691
16
Eclipse IDE Ubuntu VI Editor
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I think there was far too much documentation in the projects I've been in, and most of it will probably never be used, or become obsolete. What a waste.
 
Jeff Langr
author
Ranch Hand
Posts: 799
5
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Christophe Verre:
I think there was far too much documentation in the projects I've been in, and most of it will probably never be used, or become obsolete. What a waste.


Or worse, trick people into wasting time reading it and believing it's accurate, in which case it causes even more waste through damage.

I love economics. Once people understand the actual costs of things, they stop paying for things that they don't really want or need.

I think there are some interesting side discussions here. I have worked with many people who think stories are the artifact. That's not what I've seen work best--stories are "tokens for conversations," and are best shaped into a set of automated acceptance tests that document what the stories are about. The stories are then discarded. Keeping stories around as artifacts, IMO, costs significantly more and can lead to misinterpretation of the system.

There's another discussion around mothballing a project. I think we do want to spend some money as the project transitions to a smaller or new team.

Jeff
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Christophe Verre:
Is it true that very little documentation is produced in Agile ? What about testing documents ? Does it mean that there is no testing documents either ? Everything is decided between the testing team, the coding team, and maybe some others, and put into action by the testing team. Or does the testing team still has to make loads of printable/readable test cases ?


The best Agile teams create their tests in the form of test scripts that are fully automated and at the same time can be read and understood by the customer. It's hard to imagine what additional testing documents you would need...
 
Chris Hendy
Ranch Hand
Posts: 98
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Can you give an example of an automated test that can be read and understood by the customer?
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Chris Hendy:
Can you give an example of an automated test that can be read and understood by the customer?


A very simple example can be found at http://fitnesse.org/FitNesse.FitLibraryUserGuide.DoFixture
 
Chris Hendy
Ranch Hand
Posts: 98
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks.
 
Scott Ambler
author
Ranch Hand
Posts: 608
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
If you're interested in some detailed thoughts on Agile documentation, see http://www.agilemodeling.com/essays/agileDocumentation.htm . In particular, the summary advice at the top of the article should really help.

As far as communication goes, http://www.agilemodeling.com/essays/communication.htm should put a few of the ideas mentioned above into perspective.

- Scott
 
Christophe Verré
Sheriff
Posts: 14691
16
Eclipse IDE Ubuntu VI Editor
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thank you.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic