> Documentation only works up to a point because it can both get out of sync with what the code is doing and because documenting the internals of a complex piece of software is a rare skill. A skill that most developers don’t possess. Most internal documentation only begins to make sense to a developer after they’ve developed an internal mental model of how it all hangs together. Most code documentation becomes useful after you have built the theory in your mind, not before. It operates as a mnemonic for what you already know, not as a tool for learning.
This is ringing particularly true to me right now.
The organization I work for has allowed bit rot to occur for a number of years, to the point that it's becoming increasingly common for things to break whenever even seemingly small changes are implemented.
The "solution" that we've implemented is to require a detailed RFC document whenever you want to create or modify anything. You're required to outline every anticipated step along the way, all the tiny minutiae that you foresee yourself encountering and how you'll deal with it. And in a Google doc, no less.
This is ringing particularly true to me right now.
The organization I work for has allowed bit rot to occur for a number of years, to the point that it's becoming increasingly common for things to break whenever even seemingly small changes are implemented.
The "solution" that we've implemented is to require a detailed RFC document whenever you want to create or modify anything. You're required to outline every anticipated step along the way, all the tiny minutiae that you foresee yourself encountering and how you'll deal with it. And in a Google doc, no less.
It's utterly exhausting.