A Developer Journal – Genius or Neurosis?

Many moons ago in my first role as a developer, I had very little real work to do for the first month or so on the job, so I occupied myself with poking around the company intranet, jotting down acronyms, figuring out who was responsible for what, and documenting all of this in spreadsheets and word documents. After a while, I setup a mediawiki installation and started making actual wiki pages out of all of these thoughts. Some time (and employers) after that, this practice caught on an bit and I found myself in a position where others started using and at least getting some value out of the wikis.

For the last couple of years now, I’ve also been blogging, and before that I was in a grad program where I wrote term papers, research papers, etc. Both of these activities are a bit more focused than knowledge dumps on a wiki, but they are also forms of chronicling my experiences. So, long story short, for the entirety of my career, I’ve been heavily documenting pretty much everything I do.

When I moved into my house, I found a bunch of memorabilia and personal keepsakes stuffed in the attic. In an attempt to figure out who they belonged to, I read through some journals that were there and found that they consisted of incredibly mundane chronicling of days – what the weather was like, time awake and asleep, grocery trips, etc. It is my hope that my own chronicling of my developer life is not quite as banal as this, but even if it is, c’est la vie I suppose. And who knows, perhaps the author of those journals needed this information for some purpose I couldn’t discern (tracking a medical condition, staying organized and focused, etc).

In honor of this mystery person in my attic and my own natural tendency over the course of time toward more and more documentation, I’ve decided to start my own “developer” journal and I’ve logged my first entries this week. The journal is just a Word document at the moment, so I’m getting back to basics from my previous ascent through Excel, Mediawiki and WordPress, but I think this is good. All of those recording forms have a tendency toward hierarchical or formal organization that I don’t really want here. This is like me jotting notes during meetings in a notebook, but with less “action item: give Bill the TPS reports” and more “I just spent an hour trying to figure out why my CSS file was triggering an error and it turned out to be unrelated problem X in reality”.

Here’s what I do so far. I spend a sentence or two describing what I worked on during various time windows throughout the day or if I switch tasks. Given that I do work where clients are billed for my time, it makes a lot of sense to document that for later when I’m filling out more formal accountings of my work (though I mainly use Grindstone for this because of its precision and UI, it’s also kind of nice to have it “backed up” in narrative form for context).

In addition to that bit of context, I make notes any time someone helps me with something, introduces me to something new, etc. After all, there’s nothing worse than when you ask someone how to do X, get distracted for a few minutes, go to do X, and realize you need to ask again. I try to avoid looking like an idiot whenever possible, even if it isn’t always easy. So assists, notes, code review suggestions, etc go in here too.

And finally, I have two other things that I do. In green italics, I insert “lessons learned”. This is something like “Lesson Learned: if you compile a WPF project in VS 2010 with a XAML file focused in the XAML editor, you’ll sometimes get spurious compiler errors.” So, this is a more crystallized form of notes in that it focuses on things that I’ll probably want to remember later. The other thing is concerns/observations/suggestions, and that gets orange italics. This is things like “I see a lot of duplication here in this code and that’s a code smell, but I don’t yet have enough context to speak authoritatively.” The orange will function as a way for me to keep track of things that I think could be improved (previously, I’ve always kept a spreadsheet somewhere called “suggested refactorings” or something like that. I color code these things because I feel like at some point later I may want to assemble them into a list.

So here’s my thinking with this. I like to write and document, as should be obvious from my blogging and other documenting activities. But, there’s a clear difference between putting together nice, composed presentations/posts/essays and simply recording every thought that makes its way into your brain. The developer journal is a way to get the best of both worlds. I can jot stuff down that I’m not sure but I think might be important or that I might want to remember later, but without boring people in a wiki/blog/etc if it turns out not to matter. I guess you could say I’m keeping the journal so that I can remember more of what I think while also applying a better filter.

Does anyone else do anything like this? If not (or if so), does this seem like a good idea, or does this just seem neurotic and weird? Would you do something like this? Please feel free to weigh in below in the comments.