aspose file tools*
The moose likes Agile and Other Processes and the fly likes Documentation in Agile Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Soft Skills this week in the Jobs Discussion forum!
JavaRanch » Java Forums » Engineering » Agile and Other Processes
Bookmark "Documentation in Agile" Watch "Documentation in Agile" New topic
Author

Documentation in Agile

Christophe Verré
Sheriff

Joined: Nov 24, 2005
Posts: 14688
    
  16

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 ?


[My Blog]
All roads lead to JavaRanch
James Shore
author
Ranch Hand

Joined: Sep 21, 2007
Posts: 46
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 ]

James Shore, coauthor of <a href="http://www.amazon.com/Art-Agile-Development-James-Shore/dp/0596527675" target="_blank" rel="nofollow">The Art of Agile Development</a>. Website and blog at <a href="http://www.jamesshore.com" target="_blank" rel="nofollow">http://www.jamesshore.com</A> .
Christophe Verré
Sheriff

Joined: Nov 24, 2005
Posts: 14688
    
  16

Thank you
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
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.


A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
Christophe Verré
Sheriff

Joined: Nov 24, 2005
Posts: 14688
    
  16

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

Joined: May 14, 2003
Posts: 762
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


Books: Agile Java, Modern C++ Programming with TDD, Essential Java Style, Agile in a Flash. Contributor, Clean Code.
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
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...


The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Chris Hendy
Ranch Hand

Joined: Mar 04, 2006
Posts: 98
Can you give an example of an automated test that can be read and understood by the customer?
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
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

Joined: Mar 04, 2006
Posts: 98
Thanks.
Scott Ambler
author
Ranch Hand

Joined: Dec 12, 2003
Posts: 608
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


<a href="http://www-306.ibm.com/software/rational/bios/ambler.html" target="_blank" rel="nofollow">Scott W. Ambler</a><br />Practice Leader Agile Development, IBM Rational<br /> <br />Now available: <a href="http://www.ambysoft.com/books/refactoringDatabases.html" target="_blank" rel="nofollow">Refactoring Databases: Evolutionary Database Design</a>
Christophe Verré
Sheriff

Joined: Nov 24, 2005
Posts: 14688
    
  16

Thank you.
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Documentation in Agile