You should be writing testing notes!

And, you should WANT to be writing testing notes.

It’s not exactly a hot take or really even a controversial subject, but as a software developer, you should be documenting how to test the software you write. Though, my reasons for suggesting that practice might not be what you’d expect.

Photo by Alejandro Escamilla on Unsplash

Maybe you’re already documenting how to test the changes that you’re making. Maybe your boss or tech lead told you that you have to. Or maybe your team working agreement requires that everyone write such documentation. Maybe your issue tracking software won’t allow you to complete an issue without testing notes. Or maybe your QA team will refuse to test your change without such notes.

Those are all very valid reasons to write testing notes, but I’d argue that they mask the real direct benefit to you, the developer. The reason that I’m telling you to write testing notes is the same reason that I write these articles. You may have heard of the idea that teaching is the best way to truly learn something. My admonition to always document how your software should be tested is based on that very idea.

I’ve been writing software professionally for almost 30 years now and, admittedly, have not done a great job of documenting how to test my software for much of that time. I’m currently about 9 months into my current job and am still learning about the complex software my team maintains. Just this week I realized, while I was (you guessed it) writing testing notes for changes I’d just finished, that I didn’t yet have all the knowledge I needed to be able to coherently describe how to fully test those changes. That realization forced me to go back and analyze not only the changes I’d made, but also the larger application context surrounding the code I’d written. The need to describe how to test those changes resulted in me having a better understanding of the entire system. It resulted in me learning things I hadn’t known previously.

Photo by AbsolutVision on Unsplash

And that’s why you should WANT to be writing testing notes for the software you write even if your organization or team doesn’t require it. It’s an opportunity for you to grow as a developer, to strengthen your knowledge of the software you’re creating and maintaining. This knowledge is especially important to build when your job is to maintain software that someone else wrote.

I suppose there might be a bit of a controversial aspect to my recommendation when I tell you that you should be writing testing notes for ALL the changes you make, even the small ones. Even the seemingly inconsequential ones. It might seem like a waste of time, but I’m willing to bet that there will eventually be notes you write for a “trivial” change which jog something in your brain. That little jog might lead you to consider an edge case you’ve overlooked, or a better implementation. It might even help you uncover a bug or two. Writing testing notes for ALL of your changes is also a great way to build the muscle memory for doing so. The more you do it, the better you’ll become at it, and the easier it will be to continue doing it.

If you’re not already writing testing notes, I challenge you to do it for a week. Be thorough, and be open to how you’re thinking about your code. I bet you’ll agree at the end of the week, that you’re better off for having done it. If not, at least you’ll have made your QA team’s job a little bit easier. They’ll thank you for it.

Was this article helpful? Did you learn something? Was it worth your time, or a waste of time? I’d love to hear from you if you have questions or feedback on this article and/or if I can help you get past any stumbling blocks you may have encountered along the way!