- If it’s not code, it can’t be run through a compiler to make sure it makes sense.
- If it’s not code, it doesn’t get executed, so it may never be used to accomplish anything.
- If it’s not code, it can’t have tests against it, so there’s no way to prove that it is truthful and correct.*
Working software over comprehensive documentationSo is all documentation bad? I think you know the answer. There are many times in the life of a project when a little documentation goes a long way, and development teams should consider that it’s worth taking a bit of time away from coding to write things down. Here are some examples.
Remembering why you made decisionsIf a project goes on much longer than a few months, there will be times when decisions are made that change the course of the development effort. It may be a decision to use (or explicitly avoid) a particular tool, framework, or platform. It may be a decision to write tests a certain way, or not write them at all for some cases. It may be a decision to throw away all the practices you would normally engage in and do things in a completely different way. These decisions will happen, and they tend to last. Someday, long after these decisions were made, someone on the team (usually a new addition, they’re so annoying, aren’t they?) will ask “Why are we doing this?” What answer will they receive? If one or more people on the team with good memories have been with the project for a while, maybe they’ll get the actual reason. But in most cases, I’m afraid the answer will be, “Because we’ve always done it that way.” That is not an answer anyone really wants to hear. Now you have a choice. You can keep doing things the way you’ve been doing them, because you’re used to the pain, and it’s safer since you don’t remember why you started doing them that way. Alternatively, you can make a change and hope that you’ve considered all the possible repercussions. What could go wrong? Well..
- You could go down a path that has already been explored and rejected, wasting precious project time and effort.
- You could frustrate your customer by making a change that is in conflict with the way the business needs the system to work.
- You could violate a compliance issue that was being mitigated by the way you were doing it, and get yourself and/or your customer in legal trouble.