What documents to write in an Agile environment

09 Aug, 2009
Xebia Background Header Wave

Over and over again, the documentation discussion flares up before, during and after projects. What documentation should we make? Why do we need design documents? How can we be sure the correct software is being build if we don’t have a complete Functional Design Document. If the Functional design document isn’t in line with the actual software being build, how can we check whether we got what we paid for? etc. etc. etc.

What is the problem anyway?

The major documentation question asked: image

If we do not document everything, how do we know we’re going to get what we want before, and how can we verify that we got the right stuff after doing the project?

Of course the question implies an answer:

If we document every aspect of the project thoroughly up front, we know what has to be build before starting the work and we can easily verify whether the product delivered met the original requirements.

The problem of course is the answer was already implied in the question!

Types of documentation

In my humble opinion two types of documents live within the (software) project realm, no more, no less:

  1. Documents needed for all team members to work on the project.
  2. Documentation to be shipped with the final product.

Let us explore these two types and try and figure out what needs to be created, when and to what depth.

Documents needed for all team members to work on the project

In an ideal world we would like to hand over all work from one person to another by direct communication; talking to each other, preferably in the same room. Thereimage are however plenty of situations where it is more convenient or better to document something. Be it whether we must transport knowledge through time and space, we need to write something down, because we tend to forget, or writing something down just helps the thinking process.
However, at some point in time we, the software industry, started confusing this kind of work documents with documents that should ship with the product. Hence the weird Idée fixe that functional & technical design documents should be made in line with the actual product developed after finishing the project. When questioning people as to why they want to do this, the most common answers contain arguments like:

  • We need to know what was build
  • For maintenance purposes
  • When something doesn’t appear to work, we need to see how it was originally intended

All these reasons are bad reasons to try and maintain some big fat document that was created for the sole purpose to communicate what to build in the first place. After finishing a feature and having shipped it to a production environment, any document which was created during the building process with the intent to support this process has become obsolete!

How do we know what was build?

simple, look at the product in the production environment!

How can we do maintenance without documentation?

Any document needed to do maintenance should be created as a part of the shippable product. However this is not the same thing as a design document! Most software a) has a not-so-very-long life span (5 year old software is pretty old), Modern day programming languages make it doable the create readable and human-understandable software, thus lowering the need to create separate documentation (the code is a large part of the documentation). The important thing here is to determine what kind of documentation is really needed to do maintenance. Find the stakeholders and talk to them! In my experience, there are usually a few architecture diagrams and some supporting tables that are used, but most of the describing text is never (ever!) read.

How can we find out what was originally intended?

Well … this isn’t really important now is it? When some product is being used in a production environment, the only relevant question is: Does this software fulfill our needs? If not, what do we need to add or change to the current working product!  Any debate about what was originally intended is a waste of time.
Apparently we humans have this strange urge for others to acknowledge we were right, before we move on to the nature imagesart where we can actually work on a solution. It is just so refreshing when you let go of this urge and right away go for the core question; Do we need to make an alteration to the system?
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!

Documents that ship with the product

Depending on the product, the customer, install base, etc. etc. there will be a need to ship a certain amount of documentation as integral part of the product. Typical examples are:

  • User manuals
  • Deployment manuals
  • Maintenance manuals (intended for operating the software)
  • Technical documentation (intended for maintaining the code base)

What types of documentation should be shipped with the product is to be established long before declaring the product as done. After all, the product is not done before all parts of the product to be shipped are done! So typically, you need to agree on what documentation to ship with the product before starting to build. (Especially when in a client-vendor relationship).
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 screencasting to record. The latter is cheaper (statistically about 10 times cheaper!) and more likely to be used.
Whatever the documents are to be written in your project, please stop confusing work documents needed to support the process with documents as an integral part of the final product.


Get in touch with us to learn more about the subject and related solutions

Explore related posts