I have written this blog half a dozen times over the years, but every once in a while something comes up that makes me realize I should revisit it once more for those in the back. This time, it was a social call with a group of friends, some of whom are in high-tech, all of whom are smart and often insightful. One member of the group, a tech lead for a company that you do business with, was talking (in vague terms, of course; this person is a professional) about work he is doing, and the group started to make fun of documentation.
Let’s face it—since the very first line of code was written, we have sucked at documentation. It is a rare project that (a) gets just enough documentation and (b) keeps that documentation up-to-date. What we most often get is no documentation or documentation that records the initial design but, by the end, bears little resemblance to the code’s actual workings. The worst of all types of documentation is the “It’s self-documenting!” kind, which…
