I’ve been thinking a lot for the last few days about technical documentation, the notes that we keep as developers.
I’m in the habit of keeping documentation for the current state of the system. That’s always seemed reasonable to me. Whatever version has just been released, that’s documented well and that has always seemed reasonable and good to me.
Now, though, I’m thinking about how when I’m handing a system over to someone else the documentation they want is how the system evolved during development. The “what happened in the past” part of this is captured in version control. The “why were these decisions made” part is not, and that’s a useful piece of the puzzle for anyone who has to maintain someone else’s codebase.
I document the “how to use this” for each stable release of a codebase. I have never written down the “Why I made this decision” bit of things. When I think of how many times I’ve worked on someone else’s piece of code and the details of why this is the implementation became clear because changes started revealing why they were good decisions to begin with, I’m led to wonder if documenting intent is a good idea.
Is this what the intention behind commit messages is? The code documents the code, the comments document the pieces of the code that are non-obvious, and the commit messages document the intention behind each change?
Jam and Bees 