Once upon a time there was a programmer whom I'll call Brilliant Ken, because his name is Ken and he is brilliant.
About eight years ago, before as much had been written about agile methodologies, Ken did a project to come up with a data communications framework for use in several products. Although the project was not formally an agile project, because there was no such thing then, it followed most of the key tenets of agile methodologies, including "code for today" and "let the project team determining the optimum amount of documentation for their needs." Kevin held the hands of the first developers to use the framework, with the result that it got used in two closely related products, which is about 100% better than most platforms do. He then went on to other, useful things. A third application came along which also did data communications but with very different requirements than the first two. In an effort to show how wonderfully flexible the framework was, the team decided to use it again. It turned out that there were a lot of things that couldn't be done easily in the framework - it was "coded for today" for the first two products. Project schedules being what they were and because they were also "coding for today" they bent and patched the framework and got it to work. This year, brilliant Dave was started on a project to integrate with the products built on top of brilliant Ken's platform. There was very little documentation for the original framework, since the project team didn't need it, and what there was wasn't much use because of the bending and patching, so brilliant Dave started in to look at the code. After staring at the code until his eyes crossed, he finally broke down and called brilliant Ken, who, fortunately, still worked for the company and who has always been a very open and accessible person. Together, they eventually decided that a pretty major re-write would be needed to do what Dave need to do, in part because the bending and patching had ruined parts of the framework that were suited for Dave's needs. Currently, the whole effort is on hold. One can only speculate how a more formal lifecycle, with formal requirements documents and formal design documents, might have yielded a better outcome, at, perhaps, a smaller total cost. I can easily see how the "code for today" and "document only what you need to" dicta have helped out development organizations that have gotten caught up in writing mounds of specifications for overblown architectures. For such organizations, it's a real breakthrough to at least be able to get something out the door. For other organizations, with a different set of pathologies, the medicine might be more often fatal than the disease. Ruven Brooks