For those of you who have application development experience, how many times have you come across old code that you’d written and said to yourself, “what the F was I thinking?!?”
As someone with development experience, it’s happened to me more often than I can count. And as someone with tech writing experience, I can tell you that it applies to documentation as well.
As a technical writer, I’m often tasked with rewriting old documents that are out-of-date or no longer applicable. In the old days (i.e. before I knew better), I would essentially overwrite old documentation with the new, and often deleted the old. Now that I have more experience under my belt, I know now that that was the absolute worst practice that I could have done.
For starters, I used to have the mindset that the information in old documents was no longer relevant. The processes have changed, I used to tell myself. Why should I keep these documents around?
If you have this mindset, as I once did, I urge you to purge it. It is a poisonous attitude to have. As it turns out, old documents are extremely relevant, even if their information is out of date. Old documents are important for reference. I’ve often found myself referring back to previous versions when rewriting documentation.
I recently wound up a project that involved a rewrite of an application document. The application had been rebuilt from the ground up, and the documentation had to be rewritten to accommodate it. While documenting the testbed, I came across a number of functions that, with the limited testing dataset, didn’t seem to do anything. I went to the predecessor documentation and found what I was looking for.
Old documents are often also important in answering a simple question: why? As in, why was such-and-such process designed this way? What was this originally supposed to do? Why was this function changed? Many of these cannot be answered just by looking at application code; often, the answers are found in old documents.
These days, I make it a point to not overwrite old documentation. I back up old documents and either rename them or put them into an archive folder. I haven’t yet implemented a version control system to archive documents (we use Git in my office). If anyone makes use of version control systems such as Vault, Git, Subversion, or MS Azure DevOps (formerly TFS) to maintain documentation versions, feel free to mention it in the comments.
So if you are rewriting documentation, make sure you set aside the previous versions. You never know when you’ll need them again.