I just had a minor epiphany: not maintaining documentation is a vicious cycle. When documentation gets out of date, it becomes less useful. People don’t notice when stale documentation becomes more stale, because they’ve already stopped reading it. Many things in life seem to be this way. As the Red Queen explained, you must run as fast as you can just to stay in place. But I digress.
How do we break this cycle? One of my colleagues shared an interesting practice that other companies use: keeping detailed release notes. Instead of trying to update an entire document or corpus, you simply note the incremental changes. This is much easier, at least psychologically, because you do not have to pour over all existing documentation to make sure every word of it is up to date.
Over time, the system begins to diverge significantly from the original documentation. At that point, the original documentation needs to be revamped. If good release notes are kept, the pain of updating the obsolete documentation is greatly reduced, at least in theory.
I like the theory of this process. I wonder how well it would work in practice. Would it be hard to maintain? Would it actually make major overhauls significantly easier?