Documentation, not an afterthought

Documentation, we love it when it’s there, we hate it when it’s not. We seem to hate it, even more, when we’re the ones who have to write it. So, much like with writing tests, we make up excuses. We don’t know when to write it or even how to structure it.

I understand writing can be difficult. And we need to structure it in a way that it’s easy to read and use. It’s the same reason why I kept delaying the writing of a troubleshooting document. It also did not help that I was always the one solving the issues as well. Why would I write a troubleshooting document for myself? I already know how to solve the issues when they pop up in the synchronization with a third party.

Then my wife got pregnant again and at the moment of writing, we’re approaching the end date. That would mean I would be off, not there to solve the issues if they happen. Even worse, I can disappear at any given moment. A baby will not wait because I need to do a knowledge transfer first.

That meant I had to document any and all types of errors that could happen and their respective solution. I’m someone who sometimes even has trouble remembering what I did a day ago. So this was a challenge, to say the least. For months I treated documentation as an afterthought, and to be fair I sometimes still do. But documenting on the go is such a better move that might hurt at the moment but pays off in the long run.

I already had to change the troubleshooting document, twice! Because things went different than how I remembered. It’s so easy to think you’ll remember the steps, or why you did something. You might even think you’ll remember how it went when you ever get to writing that blog post. But, to be fair, there is a big chance you won’t.

Keep a notepad handy, type out the steps you perform and the thoughts you have. It will be so much easier and faster to create your documentation and even a blog post on it at the end of the day. Don’t postpone it until the next day. It will become an afterthought again.

Happy documenting!