There is a brief period of time between a project’s infancy and its maturity where documentation is, at best, scarce. For some projects, it lasts for a couple months; for others, until the first official release; and for others still, approximately eternity. But if all you proponents of proper programming practices truly believe that the documentation doesn’t exist… well, you’re wrong. It does exist. And you already have a lot of it.
The early stages of a project need not be maintainable, especially when it’s possible that the project will get scrapped. So it’s okay to neglect the kind of ocumentation to which you’re already accustomed: comments, design documents, change history, etc. It’s the kind that takes time, effort, and money; you know, those really scarce resources. For long-term projects, it’s usually worth that investment since such documentation lasts longer. But the mere existence of long-lasting documentation implies that there is also short-term documentation.
We never think about it because there’s really no need to. It’s natural, has no added costs, and is abundantly available in code written by humans. What is it? It’s you, the developer.
The community amongst developers is incredibly strong. They will support each other and answer each others’ questions. Still, the single best person to ask about code is the developer that actually wrote the code. He is the documentation, especially in those painfully long early stages where it’s impossible to find another source of information. Anything that you would want to get from documentation, you’ll be able to get from the developer. In fact, this kind of short-term documentation is better than any long-term alternative. Unfortunately, it expires quite quickly, and when it does, we need to push for long-term alternatives.
We naturally assume that the only reason to ever make permanent documentation is when the original developer is about to leave the company. But that’s too late. By the time the developer leaves, if he ever leaves, it’s hard to even consider him to be the developer anymore. The information gets relegated to the back of his head, locked in a vault along with other deep and dark secrets that will never see the light of day. He’ll look at his code as if it’s not his own, wondering what the hell he was ever thinking.
So when is this short-term documentation no longer good enough? Well, eventually, the code grows so large and complex that the developer can no longer explain it. That’s one good time to add long-term documentation. Another is a more specific case of the above argument: instead of adding long-term documentation when a developer leaves the company, the developer should focus on adding it when he leaves the code long enough to forget it. Of course, developers should be doing that for their own benefit anyway.
Remember that implementing this idea requires concrete action plans. Focus on how you will ensure that these notes get added. It’s difficult to get this idea off the ground at a young company, but once the procedures are in place, it will be hard to ever imagine living without them.