Kyle Smith

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

While reading Chip and Dan Heath’s book Made to Stick several weeks ago the following point caught my attention:

Many armies fail because they put all their emphasis into creating a plan that becomes useless ten minutes into the battle.

A similar problem occurs when planning a software development project.  A significant amount of planning can occur and then when the developers start writing code, the plan goes out the window.

So what is the solution?  The Heaths explain the answer to the traditional case: a concept called Commander’s Intent that was developed by the Army in the 1980s.  I had not heard of CI before reading their book, but came across it again today in James Surowiecki’s The Wisdom of Crowds.  For those not familar, here is the explanation from Made to Stick:

CI is a crisp, plain-talk statement that appears at the top of every order, specifying the plan’s goal, the desired end-state of an operation.

The CI never specifies so much detail that it risks being rendered obsolete by unpredictable events.  “You can lose the ability to execute the original plan, but you never lose the responsibility of executing the intent.”

Perhaps in the software development case the notion of CI manifests itself as a release theme or goal?  If this is true, it’s not clear to me how much value it actually provides because there are no details.

With the CI at the top of any order a soldier essentially knows the minimum amount of work that needs to be done.  With a CI in a software project plan it doesn’t seem to define the scope of the release well enough.  Or does it?

Tags: agile, commanders intent, communication, made to stick