Agile project and amount of Documentation

Question

What kind of documentation you'd recommend to support for Agile project? What are the core metrics you use to detect amount of documentation needed? Do you think you can store all of project info as TFS work items?

Answer 1

The simple answer is just enough. Just enough to communicate with your development team, stakeholders, users, etc.. Documentation should only be captured and kept up to date if there is a need for it. I think storing technical docs as close to the source code is a good thing if the developers are responsible for keeping them up to date.

Answer 2

It depends on the complexity of the project. In either case, don't write documentation that will never be read. Make it as concise as possible.

As for metrics, I have none and as for TFS, I've never used the work item feature.

And for my opinion, sticky notes and white-boards are king.

Answer 3

1. use meaningful names and structured code comments (e.g. for NDoc)
2. use a wiki for team coordination/communication, or equivalent

produce only such documents are are required for communication and figuring out the design

whiteboards are great, but difficult to post on the web - take pictures and post on the wiki

chat sessions are excellent, but hard to remember who said what; log them and post on the wiki

conference calls can be useful, but again hard to remember who said what; record them to mp3 and post on the wiki

chances are good that no one will ever read, look at, or listen to the stuff on the wiki, but the effort required to preserve it is minimal, and if it is ever needed [oh no! the lead developer just got deported!] if can be a lifesaver

and please make the code comments describe why something is being done, not what is being done; the 'what' should be obvious from the code, but the 'why' is contextual information that the code cannot express

Answer 4

Create documentation that speeds up communication and helps you move faster. Let the principle of "Mutual Benefit" guide you.

• Adoption documents: "NewPerson handbook". Getting started with any "framework" or niche tools you are using. The best way might be to get the first bunch of newbies to collaborate on refining the content... listen to the Voice of the people.
• Instructions for Setting up a development machine is another good one. Source Control server settings, Installation paths for tools used.
• Also document team conventions if any.
• Product Maps: You would need product design roadmaps - block diagrams of various top-level components and the like. Tests can serve as the always updated specs - ground zero documentation.. but you need a simple word doc ... bulleted list of high level product needs / features.
• "Here the dragons lie" - any known minefields with products (esp. legacy), 'Don't tread here' areas that you need to be careful while changing.. e.g. If you change something here, make sure you have it reviewed by Y and Z before checking in.
• Update from Dimarzionist: Stash away decisions taken during development, reasons and supporting evidence (mail chains) if needed in a 'well-known place'

Core Metric: If you find no one on the team complaining "WTH? Why didnt anyone document this? I'm stuck.. How am I supposed to proceed on this?" - you're good.

• If the team finds that they have been drawing a class diagram or sequence diagram over and over, that's proof that it is a useful artifact. Soon someone will make a sticky copy and save it somewhere to save time. Over time , the more useful artifacts would build up.
• Don't pester the team to churn out documents no one else will read...(No "This is mandated by the process")
• Don't create documents that are 40-50 pages long. No one will read them.. "Take more time and write a shorter letter" 5-6 pages max.

Finally as for TFS, once again let the team tell you. If it seems to be working well.. continue if not find alternatives & switch.

Answer 5

In addition to the other answers.

• Documentation required by the customer
• Documentation for any accreditation you need (security, life critical, banking)

Answer 6

I just joined a project which was a three-developer team. They didn't really need documentation for development because they worked very closely together. The only thing I have is code. I can tell what the packages are named, but not what they mean, or how they are related. The focus of the comments I see here is on the development, not the maintenance. I can read the entire codebase and take notes, but I think what I am doing is reverse-engineering. w/r/t "...Core Metric: If you find no one on the team complaining "WTH? Why didnt anyone document this? I'm stuck.. How am I supposed to proceed on this?" - you're good..."

Unless you plan to stay with the code forever, and never bring on different staff, I don't think this is enough for anything but extremely small projects. There may be 300 nicely commented, perfectly understandable classes, but do you want new arrivals to have to read the entire codebase and try to extract and understand the design?

Could it be that everyone is really just saying "Don't write bad documentation"? I think this needs to be reconsidered. I am trying to think about how I can take notes so the next guy has an easier time of it. I think this is an awkward way of creating documentation. I think the most expensive way to "document" your development is to establish a situation where human dialog is the primary medium. For me, writing good documentation is much more difficult that writing good code. The tools are not nearly so good, and there is certainly much less good guidance, no discussion of test.. .

I don't mean to be rude, but if we draw an analogy to coding, what would you think about comments that said "don't write code that cannot be reached - limit your code to lines that are necessary" and "don't write infinite loops"?

If we look at the hardware guys, I think we see far better tools and standards of documentation. Certainly I know that hardware to software is not always a useful comparison, but the richness and standardization of the documenting tools they have...and we have UML?

I can't argue with any of the points being made, and probably have far less experience that the other commenters. Still, I think the issue of the aging agile project is critical here. "...And for my opinion, sticky notes and white-boards are king..." I think captures the problem well.