Keep track of how you solve problems
January 11th, 2009 | Published in tip | 1 Comment
Last month while sitting at a Barnes & Noble I picked up and read a copy of Venkat Subramaniam and Andy Hunt’s book Practices of an Agile Developer: Working in the Real World. The book is a collection of good tips for developers to follow. One of them in particular, #33, struck a chord: Keep a Solutions Log.
What is a solutions log?
You’ve probably heard of the idea before or seen analogous practices only under a different name: Star Trek had ship’s or captain’s logs, IBMers have runlogs, other engineers have daylogs. In this case, a solutions log is a personal record of the problems you’ve encountered and the answers you’ve found to them, with the intent of documenting the answer for all time so you’re not burned by the problem again. If you’re kind enough to post it someplace Web accessible, others won’t get burned either!
I got accustomed to logging my activities (and by extension, the problems I encountered) while working at IBM but have been rather lax about doing the same while employed by VMware. Periodically I’d scribble notes on a sheet of paper while working but they never quite got organized or put in an easily-searchable form.
Since reading PAD I’ve been maintaining a plain text file with my progress as well as any problems/solutions I encounter. It’s already proved useful a number of times, especially when engaging in design decisions with colleagues and I know there is a particular reason to not do something. If you decide to try it out, hopefully you find the practice just as useful.
If you don’t want to buy a copy of the book (or read it in a bookstore), you can download a PDF except of the book that includes this tip from the Pragmatic Programmer website: http://media.pragprog.com/titles/pad/CodeAndDebug.pdf. You can also find additional information about the book on its official page.
One other tip in a similar vein: if you post a problem to a discussion forum or mailing list, please please please follow up with the solution once you find it. There’s nothing so frustrating as identifying people that experienced the same problem as you but not knowing how they solved it! 
Tags: agile, daylog, pad, solutionlog
January 20th, 2009 at 7:46 am (#)
[...] reading Kyle Smith’s post about solutions logs, I decided to create a new category for my blog just for solutions logs. If posts in this category [...]