Stories about Software


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.

  • Just started my journal πŸ™‚

    • Didn’t you used to do something like this with that One Note Microsoft technology at some point?

      • I have used One Note but the kind of stuff on there was more like what we would put on a wiki. The longest running thing I had done was using a continuous work ocument to β€œjournal” activity while doing defect fixing. It was nice in that when someone would ask about what I had done for a defect I would search on the defect number and see the thoughts and ramblings I had entered while I worked through the issue.

  • I do not have a development journal but I have been keeping a personal one (at least trying to) this year. In addition I’ve been carrying around field notes to jot down ideas and make notes throughout the day when I’m disconnected. I’ll have to try setting up a wiki so I can keep better dev notes. I know on many occasions I wish I had some written records to search on and save a lot of time.

    • I think the searchability thing is key for this scheme to work. Wiki (or sharepoint) does that very nicely, and a single office document does it too. Where I got into trouble with this was very early on when I was using multiple spreadsheets. That was the point where I kind of said “screw this” and moved to the wiki format. A personal journal might be interesting to do, though I have no idea what I’d put in mine – maybe lessons learned about life, like don’t believe it if you get an email from a Nigerian Prince πŸ™‚

      • I find the personal one good for goals and personal growth. I probably only do it 2-3 times a week, but it seems to be working out well so far.

  • This is a great idea Erik! I used OneNote 2010 for a while then stopped for some reason. To me, a developer that keeps searchable key notes is a more mature/smart developer.

    • I got the sense that this sort of journaling/jotting was what One Note was intended for, but I’ve never actually used it myself. Are there significant advantages of this compared to plain old Word?

      • Just better organization using what they call a Notebook which consists of folders which include pages. You can voice/video record, draw, print anything to it. No Save functionality as it always saves. You can setup to use cloud with permissions so you can access your notebook from anywhere. It’s also free form so you can start typing anywhere and add any kind of text or object anywhere on page. Searching is pretty impressive in the way it lays out what it finds. Only thing I did not like when I used it before is that the Note2010 android app sucked! Maybe next release will improve that!

  • K.Saloua

    I do keep a dev journal, but unlike you I write it in paper, I don’t know why but i feel more focus when I hold a pen and a sheet of paper then write it in word or OneNote. The problem is when I am looking for something, I use so much time that sometimes I wish if I could just write a ctrl+F and I would find what I am looking for. So soon i hope, I am going to graduate from paper to OneNote.

    • I know what you mean about focus when writing and I actually carry a little spiral notebook to meetings with me instead of laptop or a tablet. But after the meeting, it all goes right into my digital notes via manual transcription. Copying it reinforces it and helps me remember, and then I have it searchable which, as you point out, is a serious drawback to paper notes. Maybe you could get yourself a tablet with a stylus and OCR software so that you could still get the writing feel but then search later.

  • Kerry

    Many of the people throughout history, who have made significant advances for mankind, kept journals. You are in good company. Thomas Edison had 3500 at the time of his death. To find out how journaling (or more specifically writing by hand) helps develop your brain check out my blog Trapping Ideas at http://trappingideas.wordpress.com/2013/01/18/thomas-edisons-journal-habits/

  • Jake Brown

    I’ve always been a data-collector – but about different things, and usually just useful for me.

    I keep a career chronicle – where I list major projects I’ve been on (1-6 month time frame), with the dates of the project, who I worked with, my main contributions, and any major lessons learned.

    Sometimes if I had to go into a really gruesome bit of code that I didn’t ever work on, I spend an hour diagramming the call flow of the program on my whiteboard – I’ve found the process of diagramming is the useful part – the finalized documentation is usually discarded shortly thereafter – but it helps me build a mental model of the code.

    Numerous times I’ve started and stopped ‘scoring’ various activities through my day – usually I start when I’m in a rut. things like ‘did I feel healthy’, ‘did I feel productive’? Recording the data usually gets me going again, because I don’t want to have to give myself a bad score, so I start taking steps to fix whatever was holding me back. Usually after a couple of weeks, I find it burdensome and I stop (and often delete the data).

    I started a log daily-personal activities since December last year. I pick 1 or 2 memorable things I did that day and jot them down in a 2-column spread sheet. I read through it periodically, and try to reinforce the memory of what I wrote down. It helps me feel like time is passing slower, because with the log, I can remember much much more than I could remember before I started.

    Years ago I took daily gas-meter readings in my house for a couple years while I was doing insulation improvements to see what the actual benefits were. (I did that on paper, which was a pain to put into a spreadsheet so I could analyze it). I stopped after a while when I stopped making improvements, so the data stopped changing.

    • Sounds like you’ve found a way or ways to create the observer effect on yourself and use it to benefit. I bet there’s a market for things that would make all sorts of personal data collection easier. Early returns on wearables like fitbit seem to indicate this is so. It’d be interesting if you could capture mood or feelings somehow without having to be deliberate about recording them.