There are many ways sure-fire ways to make certain that a software project dies. The well known (and well discussed in numerous books and articles) ways include being over-budget and/or late, delivering buggy code due to inadequate testing, and tyring to create something complex with little or no requirements, plan or discipline.
These are the ways of the quick death (mostly).
There is yet another way, even more insidious, to kill a software project and any future prospects for future re-use. It can be like slow poison, sometimes taking full effect long after the finished code has gone out the door. Its effects can linger far longer, tainting anyone associated with the project.
I’m referring to documentation. Yes, that stuff with all the words that many developers detest.
The documentation I’m thinking of isn’t just the user’s manual. It’s all the words necessary to define, implement, verify and re-use software. It’s everything that describes the project and the code that will result from it. It’s the detailed requirements, the design documentation, the test cases and test procedures, and, last but not least, the comments in the code itself.
There seems to be a trend nowadays to refer users to the source code if they have questions about how to do something with a particular piece of software other than just use it as-is out of the box. This seems to be particularly common with interpreted languages such as Python, Perl and Tcl. It never fails to annoy the hell out of me when I’m trying to use something and I get the point where the skimpy documentation states “refer to the source code for details”.
No. I refuse. That is a waste of my time, and a rude and inconsiderate stance on the part of the developer. If that person really wants me (and the other busy folks in the world) to drop their software and go in search of something else, that’s an excellent way to do it. Even if I can’t find something that has all the features of the rude-boy code, I’ll go with the alternative anyway if it has good documentation with it.