The recent trend in software development has been to produce less documentation and writing material. Many developers have interpreted the Agile Manifesto preference of “working software over comprehensive documentation” as the authorization to stop producing any document during a project. This has been translated in sentences like “the code is the documentation” or “the requirements are in the application”.

There have been certainly many projects that have produced documentation only for the sake of documenting. You could have heard the famous tale about the 200 pages requirements document that contained a sentence like “the first one who would report reading this section will receive 100 dollars”. Remember however that the Agile Manifesto says ” while there is value in the items on the right, we value the items on the left more.” There are many aspects of software development that will benefit from writing more than code and there is certainly value in doing this. If I didn’t believe that writing material has some value for software developers, Methods & Tools would contain only code listings.

For me the first benefit of writing is to validate if things are clear in your mind. If you think you understand something or know what the design of your code will be, having difficulty to write it is a sign that maybe you should try to think more about it. The benefits are not in the results but in the process. It is the same thing when you try to define acceptance criteria for a requirement. If it is difficult to write a description or some functional tests for it, then your requirement is maybe not so clear.

There is also some specification of the software that cannot be found in the code. If the first screen of your web site or mobile application has to be loaded below a certain amount of time, you need a place to keep this information. If your screens have to respect accessibility standards, you also need a document to register this information. Agile software development recommends sometimes to use “soft” material like index cards or post-it to manage requirements information. However, good applications have a life span that is longer than their development time… and often their development team. I don’t think that organizations will want to keep forever meeting room walls full of index cards. You need a support that can be available for a long period and that has search capabilities. Over the time, there will always be people asking questions about the features of the software. Having the original requirements written down somewhere will allow you to answer if the application is working as specified or if you have introduced a bug in it. Yes, bugs still exist, even if you try to follow an Agile software development approach ;o) So my advice is that you should keep writing down requirements and other useful information about your application: do it for you and for your colleagues.

Further reading

* Is “agile documentation” an oxymoron?

* Is Documentation Really Wasted Effort?

* Agile User Documentation