Documentation for Progress
I’ve noticed in my work recently that documenting my work is one of the most reliable ways of making steady progress. I likely gathered the idea from the internet somewhere, or perhaps from the generous amounts of advice spewed forth from my postdoc. But I do remember, when I was looking up some stuff surrounding the scheme publishing language, skribilo I came across the Nonpareil Project. The author, Jeffrey H. Kingston has kept a nice summary log of all the detailed work that goes into such a project. I’d like to quote a bit, just to give the flavor of the summary:
22 March 2007. The new version of the type system is compiled and tested today. This is about 12 days after I started the revision. The next problem, causing a core dump today, is that range types get frozen but are left unresolved at the end of MatchFunction, so we can’t be sure about coercions and run-time types at that point; we have to defer those until we descend again, during code generation. So there is some re-thinking and rewriting to do there.
23 March 2007. Sorting out the relationship between coercions and subtype tests. This has led to a realization that subtypes have to be tested twice: once when manifesting, without asking for coercions because they are unavailable in the presence of range types, and once during code generation after range types have all been resolved, at which point an error could occur. Also privatised expr_rec further, hiding it from its own subtypes.
28 March 2007. Finally finished working on the relationship between coercions and subtype tests. There were two problems: when the upper constraint is a meet type, and when the lower constraint is a variable. Solutions to both have now been documented, implemented and tested. The next step is to insert subtype calls, and the resulting coercions, during code generation.
As you can see, it’s a pretty high-level summary of the coding concerns for that day. This log runs from 2002 to 2008, and documents the progress of the project. Since, I’ve now moved to WebKit in my Information Flow project, I’ve also started keeping a similar log. Recording each minor milestone of implementation work. I’m expecting this log to help me write my thesis, as it will give me remembrance of details that I might otherwise forget.
I’ve also experienced a secondary benefit from keeping this log. The desire to grow the log, compels me to make progress in my work. I’m motivated to do tasks, just so I can mark them as done in the log. Additionally, since the log is geared toward recording smaller changes, I can break big todo’s up into a series of loggable items. I no longer get flummoxed by thinking of the sum total of work that might go into the implementation. Instead, I’m motivated by smaller tasks, which are easily accomplished.
Finally, the very act of documenting the work, and putting my thoughts into words, has helped to concretize my ideas and concerns. Instead of worrying abstractly about nebulous feelings, I now have mold them into precise explanations. Doing this helps me to realize which aspects are ignorable, and what specific actions I can take to answer the open questions.
Finally, I have a technique that allows me to make steady, targeted progress.