Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News Two Types of Agile Documents - No More, No Less!

Two Types of Agile Documents - No More, No Less!

Leia em Português

This item in japanese


Agile Manifesto suggests “Working software over comprehensive documentation”. This has led many teams to believe that there is no need for documentation in Agile projects. Critics of Agile use limited documentation in Agile to showcase the weakness of Agile methodologies. Ron Jeffries, suggested that Agile does not recommend no or low documentation but places a lot of emphasis on the right documentation. He mentioned,

One of the most common raps against XP isn’t even true. People think we say that documentation is a bad idea. XP is focused on conversation for maximum effectiveness. Our recommendations on documentation follow from that simple fact.

On similar lines, Eelco Gravendeel added that there are just two types of documentation in Agile,

  • Documents needed for all team members to work on the project – In an ideal world, the team is collocated and all the knowledge would be shared and transferred by direct communication. However, if the team is distributed and the knowledge has to be transferred then writing documents and supplementing it with audio/video calls would be useful. A minimal common document set is also required by the teams to speak a ubiquitous language and be on the same level of understanding.

Eelco suggested that many documents, which are created to support product creation, call for a closer attention since they are disposed off as soon as the project is over. According to him,

As soon as you accept that documents that are solely written to support the product creation process are to be disposed of as soon as the project is finished and the product is delivered, you hopefully also can start resisting the urge to make any such document over complete and 100% correct! This is exactly why writing documents is such a time consuming (and therefore expensive!) task. Once you accept that you just need to write down just enough to convey your message or to support your memory, you will also understand that pen & paper, photographs of whiteboard drawings, scribbles on the back of a coaster, story boards, etc. suffice for these purposes!
  • Documentation to be shipped with the final product. - These are the document which form a part of the product delivery and are decided well in advance with the client. Typical examples include

  1. User manuals
  2. Deployment manuals
  3. Maintenance manuals (intended for operating the software)
  4. Technical documentation (intended for maintaining the code base) etc.

Even for these documents, Eelco suggested,

When you've agreed on what documentation the product should ship with, you can still be creative as to the form of the documentation. You can write lengthy user manuals, or you could use more 2.0 techniques like screen casting to record the documentation. The latter is generally cheaper (statistically about 10 times cheaper!) and more like likely to actually be used.

Thus, there are two types of documents, one which help the team and others which have to be delivered with the final product. If an Agile team is preparing documents which cease to exist in either of these categories then those documents call for a closer attention. In most cases, the team would be able to avoid these documents.

Rate this Article


Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Community comments

  • What should VS what has

    by Mike Bria,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Agreed. I've always described this to people as "docs to capture/express what SHOULD be built" versus "docs to capture/express what HAS BEEN built".

    In general, the "working software over comprehensive docs" is talking much more towards the former of the two. Nonetheless, certain agile practices will also often greatly decrease your need for the latter as well (TDD and STDD, clean code, system metaphor, collective ownership, etc).

  • Re: What should VS what has

    by haixiang xu,

    Your message is awaiting moderation. Thank you for participating in the discussion.


  • What should VS what has

    by rey bumalay,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    I have to agree with this.

    And IMHO, documenting without totally understanding how a certain stuff & technology works will end up with document continuously being revised and time wasted.

  • great!

    by Marcelo Andrade,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    I love the tip about screencasting the user manual documentation!

  • Representational vs. Evocative documents

    by Amr Elssamadisy,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    An idea I learned from David West is the difference between evocative documents and representational ones.

    An evocative document is one that evokes memories - an example would be a collaboratively created object model of a system; for anyone who participated in its creation, the model evokes the conversations, arguments, mood, etc... when it was built - this is a very powerful type of document.

    A representational document, on the other hand, is one that we believe that represents reality. These documents are the typical ones we move around and "throw over the wall", thinking that the documents represent the system and therefore anyone reading the document will "understand". This is almost always incorrect and is a very large source of errors from documentation.

    Finally, you can read more in this chapter on evocative documents.

  • Re: Representational vs. Evocative documents

    by Mike Bria,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Very good, I like this a lot.

    I often find that documenting the "high-level roadmaps" of the main ideas and "big rocks" can be helpful.

    Not to convey "understanding", not to represent the details, but just as a means to get people started in the right frame of mind.

    I'm not sure this would classify as "evocative" though, because it is intended also to help people who may not have been around during initial discussions.

    Nonetheless, helpful ideas.

  • Re: Representational vs. Evocative documents

    by R Streefkerk,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    The title of this article is still misleading. If i want to evaluate my software architecture solution with stakeholders. Word of mouth is not going to be sufficient, neither does team member documentation.

    The general idea of document what you need is supported in all software engineering practices these days.

  • Re: Representational vs. Evocative documents

    by William Martinez,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    You can read the discussion in the Virtual Panel on Software Architecture Documentation.

    One of the points I made in the comments is that documentation should be driven by use. I don't care if it looks nice in the wall, or if it may be helpful for others (stakeholders or newcomers) to understand what is happening, or what would happen. If it is not put into use, it is waste.

    So, the main problem may not be the type of docs that are created, or how. The important thing here is if the team is using the docs. AND, if using some kind of docs will improve development. (Note Development is a very huge concept, not just coding).

    William Martinez Pomares.
    Architect's Thoughts

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p