Neil Macy

Writing Documentation For Future Me

I was working on some code in my day job recently and trying to figure out how something in a shared library worked. When I looked at the docs, it was described pretty thoroughly.

I wanted to thank whoever it was who wrote the documentation, because I had been pretty unclear on how the code worked. So I used git blame to find out who the author was.

It was me, from a year ago. I had zero recollection of this part of the codebase, and thought it was my first time working on it, til I saw that Past Me had already been there, hit the same problem I did with understanding, and added docs so that others could avoid getting stuck in the same place.

I always try to write documentation from the point of view of someone who has no idea what’s happening. It’s amazing how often that helps Future Me.

Published on 1 June 2023