Documentation

When you’re in a small team and things are moving fast, documentation is important. Yes, documenting your code is important and the issues around it are well known. You do document your code, right? Documenting assumptions and decisions is more important.

There’s always pressure to be “agile” (don’t get me started), and even in a waterfall development model, you will need to make changes during development. Document the issues that led to the changes and why you decided to make that particular change. Eventually you will find yourself asking, why did we do that? If you have even basic documentation around midstream changes, it makes life so much easier. (And don’t forget to include the date when you made the decision. Sometimes knowing the sequence in which changes happened can make all the difference, although you can usually reconstruct sequence using source code versioning. Don’t count on it.)

But the hardest kind of documentation to do, and the one most often missed, is to document assumptions, as many as you can. They can be critical when it comes time to do testing or to evaluate future changes, or even when handling support calls.

Yes, I do mean that you should take the time to put together this type of documentation even if you’re a one-person development team. Six or twelve months down the road, you may not remember all the details of what you decided when. If you’re business expands and you need to bring on additional help, or if you’re in a larger team and you have turnover, this kind of documentation can make maintenance and enhancement go much more smoothly.

I may have been dealing recently with a project that has suffered greatly because the previous development team assumed that they would be doing the work so they didn’t document everything. Then the project was dumped on an entirely new team with little to no experience with the project. We should be out of the weeds in another week, but it’s not been a fun process. Now, every time I’m tempted to cut corners, I’m going to remember this project.