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

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.