Agile in Bangalore agilebangalore.groupsite.com

IMO, Documentation is important and required but it should be minimum, sufficient and simple. I would like to share below link where Scott has explained it in more detail:

http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm

A few factors to consider while considering the documentation required 

• How much is enough ?
• Is there a way to make it "generate" rather than "create manually" ?
• Can this be a live document and just-in-time elaborated incrementally ?
• What is the shelf-life of the information created ?
• Are we doing gold-plating of the document ?
• Is the document helping us move forward or is it a trace for people following in the software development path ?
• Whats the DONE definition for the document ?

Hi Ajay, Ans IMO

How much is enough ?
=> Domain User has to understand what is written.

Is there a way to make it “generate” rather than “create manually” ?
=> Aha.. please elaborate.

Can this be a live document and just-in-time elaborated incrementally ?
=> should be.

Others are questions to me too.

Thanks

Documentation is not just user doc. How about developer docs?

instead of having only subset of the system, documentation should be prepared for every one who touches the system. Then only system will be used as it should be used.

what say?

IMHO

There are 2 types to documentation (and the Agile principle is minimal but sufficient documentations)

1) Documents supporting delivery to external customers (this can be Release notes, User guides, Admin guides etc)....I don't think there is any scope of reducing this type of documentation

2) Documentation supporting internal delivery - e.g: Status Reports, Meeting Minutes, Specification documents (Use Cases Diagram, Functional Specs, Tech Specs etc etc)...again sometime a few of these are mandated (in service companies, clients may ask for this before transition to support)...however the Agile principle should be to question the need and detail needed for each and take the minimum but sufficient approach...e.g: If client wants a Use Case diagram before the transition, I will take the following approach...thruout dev cycle I will NOT manage any document but rely on .MDL files to manage by user cases, classes, sequence diagrams etc and in the last sprint keep a story item to create a use case diagram....by that time the components of the mdl file would be stable and it would be easy to create the document (in fact tools like Rational Rose may just create it for you)...Similarly I will NOT waste time on multiple status reports (no reports of scrum meetings etc), however make sure the team is capturing the relevant and important "conversations" in some sort of documents...

Bottom line....Agile is not for NO documentation it's for any documentation that has a purpose AND the simplest way to deliver those...

Ani

wholeheartedly accepted your points. Aniruddha. OTOH lengthy documents by its own length prevents itself against chance of being read :-)

Thanks

Vinay, I believe the question that is the topic of this discussion is wrong. "Do agile methods require documentation?"

I don't want to split hairs, but the answer to that would be "in case of Scrum, the burndown charts, product & sprint backlogs and the retrospective notes are the documentation".

Obviously that is not what you mean but I believe those kind ill-phrased of questions are largely responsible for the very misconception in this topic. Please... no offense intended, just speaking my mind here.

I believe the actual question usually should be "does our project require documentation?" whether you use an agile methodology or not.

ISO (certainly not agile originally) does require a certain set of documents, although I believe ISO does not tell you how each doc should look. Neither do agile methods (personally I can only speak about Scrum).

Agile methodologies give us the freedom to ask the question "how much documentation do we (team, managers, stakeholders, customer, user) really need?" and deliver just that, in a format that is useful to us in a quantity and quality that matches our need without creating waste.

A proper answer to that question must involve a discussion with the customer. There is no one-size-fits-all answer. Not with agile, nor traditional methodologies by the way.

Regards,

Dominique

Team

I think Dominique has put it really well...if given a chance I would just change his alternate questions in my way -

Instead of asking "Does our project require documentation"

I would ask

"What is the minimum (necessary but sufficient) documentation that my Project Users need"

In my experience that has worked better - it let me identify my users (types - stakeholders, product/project end-users and engineering community) and their minimal needs AND handle that in the simplest way that satisfies them.

Burndown Charts, Backlogs (with conversation and clarification stressed upon) and Retrospective notes are good enough for MOST mature scrum/agile team's internal documentation needs (if there is more need...it is most probably a company rule or the team is doing wasted work that no one REALLY reads - e.g: Meeting minutes)

User Guide, Release Notes etc may be the minimal that external users need. So identify and deliver the minimal subset (with precise and sufficient content)

For stakeholders (outside Engineering/Scrum Team) - e.g: senior mgmt OR field facing orgs (who need training docs may be?)....Identify the minimal set of docs, get agreement on these and stick to them (e.g: I may send ONLY velocity chart to senior mgmt and or agree on a final sprint story to create 2 training docs - technical overview and deployment overview)

Regards

Ani

All,

Thanks for the comments and really it's good to see the different angles of this discussion.

The point mentioned by both Dominique and Ani is valid, that's a generic question that really everyone should think through prior to start of any project irrespective of Agile or traditional.

However, my intention in this discussion was to talk about importance of documentation in agile methods. Let's take an example of ISO or CMMi or any other standard that is followed by any organization (mostly they follow traditional methods), do they really think on whether the project really needs those heavy set of lengthy documents? As per my experience, no. Not at all. I am not going in deep to find out the initial need of those standards in the organization.

Another part is when anyone starts following agile methods in same organization, the strong resistance comes from those groups responsible to set or follow those standards. This is because of one myth "Agile methods don't need documentation or care on documentation". And all of us know that it's not true.

My point was to discuss to get an overview on documentation aspect from various organizations where people follow agile methods. People should discuss how much importance is given on documentation and for what.

As all said we should think on how much (minimal) documentation is required for the project and again definition of minimal vary person to person, team to team and organization to organization.

Thanks,

Vinay

Thanks Ani you put my thoughts down even better than I did myself :).

@Vinay: You refer to a "heavy set of lengthy documents" in ISO and CMMi.

We are an ISO 9001-2008 company and we do Scrum compliant with ISO. All we add to the usual Scrum artefacts (backlogs, burndown charts, retrospective notes) is a risk assessment which is a good idea even without ISO.

I'd neither call a risk assessment "heavy" nor "lengthy".

Which documents being mandatory to ISO are you referring to exactly?

Regards,

Dominique

Dominique - My intention is not to point out ISO or CMMi documentation. My point was same that while following agile also one can achive it what already you are doing in your organization (Its really an example for everyone).

Since Agile never restricts us for documenting, only it says to analyse and decide whether it really a need in our case or not.

I hope I answered your question.

Thanks,

Vinay

Hi Vinay,

yes, it's clear now, thanks for your patience with me :).

I guess the mayor point is that traditional methodologies do not encourage people to question the status quo, in contrast to the "continuous improvement" mentality in Scrum and other agile ways.

Take care,

Dominique