Wednesday, February 09th, 2011


This article briefly explains why documentation is required in development of software projects, what types of documents you should create and myth about agile documentation.

‘Working software over comprehensive documentation’ 2nd manifesto of agile software development ( .  In traditional approach, you will find most of documents shown in Fig-01 are created before the development phase (coding) starts.  The project starts with requirements phase, design phase etc each phase deliverables are just documents. Progress is ZERO until the coding phase starts. Documentation is not one time activity, you need to maintain it (update & reviewed) so more time & money spent.  Sometimes project fails due to hefty documentation i.e. exceeding project budget or delay in completion.

Do we need really need all the listed documents? NO, Travel light. We get more business value in working software than in comprehensive (broader in scope) documentation.  




Agile myth: Zero Documentation

Some believe that Agile doesn’t require (or, even, cannot support) documentation.  Agile manifesto never says documents are waste or not useful.  Agile documentation says: travel light (Write fewest documents), Just-in time, Update only when it hurts.  You may save time & cost without documents but the project may fail in long run i.e. when the project is given to another team for maintenance. In simple words, no projects should be developed without supporting documents.

Why Do People Document?

  • To support organizational memory

Working Software is Your Primary Goal.   An important implication is that we not only need to develop software, but we also need to develop the supporting documentation required to use, operate, support, and maintain the software over time. 

What type of documents do you need?

  1. Project Proposal

    Think about the environment before printing!

    Think about the environment before printing!

  2. Product Backlog: list of features to develop. Link features to use case doc
  3. Use case/User story/Feature Specs: covers
    1. Use case scenarios & screen prototype
    2. business rules & validation messages
    3. class diagram (nice to have)
  4. Design & Architecture document: consists of
    1. Technology, frameworks chosen for the projects
    2. Sequence diagram to explain execution flow
    3. Explanation on layers of architecture (mostly MVC2)
    4. How to develop & configure? Code snippets on view, controller, model, configuration files etc
    5. Non functional requirements
  5. Quality management:
    1. Defect tracker
    2. Functional test cases
  6. Build & Deployment document: covers
    1. System architecture/Deployment diagram
    2. Environment details e.g. IP details of DEV, TEST, UAT, PROD environments
    3. How to build & deploy?
    4. Labeling/Versioning strategy, SCM details
    5. Configuration Management details
    6. Post-deployment verifications
  7. Miscellaneous documents like
    1. Traceability matrix

I strongly encourage Product Owners to produce User Stories/Usecases/Functional Spec documents because they connect very deeply with the project, rest of the documents should be created & maintained by project team (Architects, Developers & Testers).

Also visit:

Category: Agile/Scrum
1 Star2 Stars3 Stars4 Stars5 Stars (No Ratings Yet)
You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

2 Responses

  1. I usually do not write a bunch of responses, but i did a few searching and wound up here Agile Documentation – Travel light | Prowareness Developer's Blog. And I do have a couple of questions for you if you usually do not mind. Is it only me or does it look like a few of these remarks look like they are written by brain dead people? 😛 And, if you are writing at additional sites, I would like to follow anything new you have to post. Could you list of the complete urls of your shared pages like your twitter feed, Facebook page or linkedin profile?

  2. I’m usually to blogging and i really appreciate your content. The article has actually peaks my interest. I’m going to bookmark your site and hold checking for brand spanking new information.

Leave a Reply


This blog is kept spam free by WP-SpamFree.