On Development Logging: The DevLog

I’ve always liked having a record of what I’ve done on a project and a place for notes. That’s often been a notebook, updates to GitHub/GitLab/JIRA issues/tickets, or maybe blog entries. Those all have problems. In reading Masters of Doom I came across a passage which described the intense environment around the development of Quake. John Carmack came up with a concise running log of what he was doing, called a “.plan” file. It provided a frictionless way for him to keep track of his progress, the things he wanted to fix later, notes he had to himself, etc. He used it for himself but also posted it to the internet to keep the gamer community informed. You can read the whole archive of them from 1996 through 2010 here , although after 1998 they were more like a blog. I decided to tweak the style of his 1995-1998 system slightly and have been using this modified process for tracking my development on projects since November of last year. I call these files DevLog (very creative I know) and find it works so well that I’d share my methodology here.

I like keeping track of things I do but I like doing it with as little overhead as possible. Hence I have years of food data tracking but that only really started being real when the ability to enter that data became so simple as to be effortless. The same is true for development on projects. I want to see how things evolved. When I look at something years later and think to myself, “What the hell was I thinking?” it’s nice to be able to look back at notes from that time. Likewise as I’m working on something and I have a thought pop in my head like, “We need to fix this later,” or, “Gee wouldn’t it be nice if this program did this thing,” it’d be nice to have a place to collect all of that and have it be something which doesn’t interrupt my train of thought. I’ve tried collecting that in issue trackers and the like but honestly I’ve never been able to keep up with that. Issue trackers that become the reservoir for things to do start having inefficient signal to noise ratios. Even when I thinned out old issues it often proved hard to find what I was looking for as well. Lastly it also disrupts the flow.

Carmack’s “.plan” file concept was an absolutely perfect solution to this problem. It’s a simple text file you have open and you put in short statements with a simple key that you can decipher instantly. It’s searchable so you can easily find stuff. It’s shareable so it doubles as providing status as well as a means of keeping track of your own thoughts. Lastly, everything about the project is in one place. I don’t have notes in one place, issues in another, feature ideas elsewhere, etc. While I liked Carmack’s idea I have tweaked it a bit for my own purposes.

The first tweak I have is that each project gets its own DevLog. I started off trying to have it in one big file but since I work on multiple projects it just didn’t scale well. Since these are text files there is no disadvantage to having them split out since search tools can just as easily traverse multiple text files in a directory as one big text file. In the rare cases where something I’m working on is related to both projects I make a footnote in the one about seeing something in the other or some other mechanism. It’s such an uncommon occurrence even on projects that have entanglements that I don’t worry about it. So if you look at my DevLogs folder it looks like this:

.
├── 2020_B612.txt
├── 2020_Hipparchus.txt
├── 2020_LiteDb.txt
├── 2020_Mammoth.txt
├── 2020_MySocialPortal.txt
├── 2020_orekit.txt
├── 2020_Spacekit.txt
├── Archive
│   ├── 2019_RunningDevLog.txt
│   └── 2020_FT6.txt
└── README.txt

As you can see each project gets it’s own file. To keep the length to something reasonable, especially for very active projects, I’m going to roll over the file each year. There is an archive folder where previous years and projects that I’m no longer working on are stored. So what does the DevLog file look like? Let’s look at a section of my log for work I did on Spacekit.js back in may.

==== 11 MAY 2020 ==================
If nothing is in there there is no redraw being done (unlike in demo)
Some drawing objects are being rendered not cached therefore when it's time to remove it lacks the references
Should objects manage their own objects in the scene as part of an interface?
Because things like labels are outside of the scene we should move the "remove object" code to an interface that can be called
# Fixed label and marker removal code


==== 12 MAY 2020 ==================
# Fixed Resizing window jacks up labels even when animating
# Fixed Label positions don't updating during a camera pan if not animating
When animating the label position updates and corrects it after a non-animating pan
Can't figure out scroll wheel zooming, not intercepting that event... (just pick up camera changes)
# Fixed label updates and resize 


==== 14 MAY 2020 ==================
# Completed EphemerisTable and fixed some interpolator and binary search settings
+ EphemerisTable needs a function for returning an orbit using start/stop and step
+ Implement lookup ephemeris and make simple example
+ Check if "orbit around" really only valid for particle system still (no)
+ Implement advanced look up ephemeris scenario with:
	+Lookup ephem for marker and label with drop lines
	+Lookup ephem for rotating body (doubles for shape)
	+Lookup ephem for orbit around another object that is ephem
	+Lookup ephem for orbit around another object that is lookup
	+Regular ephem object around lookup ephem object
- Example of multiple viz windows with animation times linked
- Update depracated THREE.LineStrip
+ Confirm delete works
+ Fix performance on the nested orbits example
+ Fix zoom to fit


==== 15 MAY 2020 ==================
# Fixed zoom to fit
# Implemented lookup ephem
# Send email asking why original limited orbit arounds to sprites

Even without knowing what the symbols leading up each row is you kind of get the gist of what I was doing at the time and what I was struggling with. Again it is a frictionless way to keep notes and track of things. I literally have a text editor up and as I think of something I jot it down quickly. As I finish something I change the symbol. If I think something sounds familiar I scroll up a few days or do a search. Again, it’s all frictionless. So what about those symbols? This is where I’ve built on but diverged a bit from Carmack’s original .plan file. I document it in the README file so it’s easy for others to decipher, but it’s pretty simple:

Day Separator:
==== DD MMM YYYY ==================

Legend
'' (no leader): A note
* : An item to do later
# : Item completed same day
+ : Item completed but on another day
- : Item going to be ignored
T : Item transferred from one archive to another

Each day gets it’s own separator with the same format, so it’s easy to see the progression of things over time. The rest is pretty self explanatory. Simple notes have no leader. An idea I have for something I would want to do later is given a *. If I complete that item on the same day it turns into a #. If I completed that item on another day it turns into a +. Often times I use the # to mark work that I accomplished that day as well even if it never had an original * item. If at some point I decide I’m not going to implement one of those ‘*’ items then it gets changed to a -. The - is often an adjudication that comes up when every once in awhile I go back through the last few days or week of the log and decide something isn’t worth doing. Lastly the ‘T’ is something that is transferred from one log to another, usually with some annotation of where. This mostly happened when I started the 2020 logs. Dangling items at the end of the year that really should “graduate” into the next year should be pretty minimal. This just marks that transition.

I don’t really do much work with a development team that requires statusing of what I’m doing, but if I did I could easily see something like these things being stored in a shared folder area, something like Google Drive, or a repository of some sort so that it was easily get a glimpse of what people are working on at a given time and also to perhaps gain insight on related development without needing to interact with the developer all the time. That was the intention of this system at Id as I understand it.

I’m not sure if this will be as helpful to others as it has been to me but I thought it was worth sharing. If you want to see one of my logs updated in real time you can keep track of the development I’m doing on a from scratch ray tracer that I’m writing using the Ray Tracer Challenge Book . That log is here {:target="_blank}. I’ll have blog posts later about that too, hypothetically.