Keeping Dev Logs
In my assembly-nights project, I started taking really detailed notes of my progress as a way to organize my thoughts and motivate myself (and possibly entertain other readers).
Since then, I’ve been pretty regular about using "dev logs" in my personal software projects.
This is an extension of the next-note and run-sh concepts wherein I leave active breadcrumbs for my future self when re-joining the project anywhere from a day to months later.
I also made extensive notes as I thought through the trials and tribulations of Meow5 (the project for my assembly-nights2). These notes absolutely saved that project when I left it for five months. By re-reading my log files, I was able to get back into the state of mind and state of the project in a way that would have been very, very difficult to do with the source alone.
Another recent notable example is my static website repo publishing tool: RepoRat. For that one, I not only recorded my progress, but also kept track of how long each part took, in minutes.
I logged my time because I wanted to see how quickly I could build it. (My personal projects have to fit around a day job and family commitments, so I don’t blast stuff out in 36 hours straight over weekend anymore.)
That worked out great, but it also kept me on track. I tend to "go off into the weeds" on personal projects. Knowing that I was timing myself kept me on task. This probably sounds terribly like work…but you have to understand that I wanted RepoRat to exist and I wanted to be able use it as soon as possible. These were my goals and accomplishing them quickly was for my satisfaction.
Devlogs as a truthful method of learning in public
My dev logs are very truthful. When I realize I’ve made a mistake, I don’t go back and edit the old entries. (What I have done instead is add a clearly-labeled "update" note for myself and others as a warning about the wrong turn or misstep.)
And actually, I think it’s pretty fun to be able to write "oops!" and document my change of mind.
(Deep down, I also hope that some newbie someday comes across my mistakes and sees that the project turned out okay even though I screwed up. I want to see more humanity and humility in the programming field.)
So, these logs are append-only, if you will, much like my pocket notebook "capture system".
I came across a summation of similar ideas under the "append-only" name in this post by Zsolt Benke:
"I can always add a follow-up to an entry but I should never change it, so I can see how something was developed over time."
(Ha, and wouldn’t you know it, Zsolt also linked to my notes page about my paper notebook system. Cool!)
Writing with a pen in a paper notebook is probably what first got me over the hump of self-editing. Jotting stuff down as it happens and figuring it out later is a fantastic way to re-live the whole thought process and re-think it as well. It can be an interesting way to essentially brainstorm with your past self.
Kinda related: note-to-self