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
First of all, this isn’t recent. It started when software development came under the purview of hobbyists, and frankly, there it has remained ever since. Prior to the home computer “revolution”, code was the last thing that was written. Specs, testing, etc., were all written before hand, and documentation was maintained during the process. I’ve worked on enough of these well-funded projects to have experienced the difference. Take for example the code that was written for the moon landing missions or the space shuttle. Every line commented, tested, etc.
Agile is a thoughtful but still knee-jerk reaction to a bad situation, brought on not just by degreed garage shack programmers but also by companies that cut costs by forcing ridiculous development schedules, little up front design time, and very little testing / documentation support. I’ve worked for a billion dollar aerospace firm, and the short-sighted management refused to let the engineers spend the necessary time to meet and flesh out the design of the wirelist generation software up front, something that would have saved the company millions every year and greatly reduced wiring errors.
I totally agree with you. For years I have heard coders say, “The code is self-documenting”. I could only silently scream when I hear them say that. After coding for 40 years now, I have had my share of supporting other people’s code as well as some of my own that I have had the privilege some 10 years after inception and I still concur.
When selecting a book or a magazine to read, dont we look at the table of contents and the typefont to get a feel for how easy it will be to assimulate what the author has to say?
As another crusty old engineer, it’s true that this desire to avoid documentation – or find ‘easy’ ways to reduce it – are not new, but it’s nice to see a new article taking a stand to say it’s important to maintain the extra work required to fill that human understanding between code and the end need.
“although the right items are important, we value the items left over” This is the statement that comes right after the agile manifesto. Many ignore and resolve only consider working software over comprehensive documentation. Your criticism are correct however you made ??a mistake by generalizing agile projects as if they were just a wall full of papers. This is a very simplistic view. The post-its are just a tool. The agile management process is much more than that. And yes the documentation is done, but it is usually stored in management tools. The advantage is that now it is in fact what was built. Very different documentation than 30 years ago it was a photo of the initial vision of the project and the first transition was outdated.
Pingback: Software Development Linkopedia September 2013
Pingback: >kloctalk | What can software developers learn from storytellers?