
- 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 decisions
If 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.
3 Comments on this Post
nate.mckie
Thanks for the feedback, Craig! Yes, having a place to put things where everyone can find them is very important. If you can make the code repo work for that, great; I’ve not seen anyone do that effectively yet because of the issues of searching through it. Maybe you can share your ideas if you come up with something good.
Metrics link fixed; thanks for the heads-up.
Craig Buchek
Excellent article, Nate.
I’d already come to the conclusion that we need to document a lot of the decisions that we make during a project, but have not been able to come up with a good way to accomplish that. I think having a place where such documentation “belongs” would be a good start. (For me, that would usually be somewhere in the code repository.) Having it as an item on the code review checklist would probably help as well.
PS. The link to the metrics article is broken.
One Trackback for this Post.
[…] Blog Post – I’d Rather Be Coding – Documentation […]