Technology Blog

Take note: Take notes!

Posted by Bill Shaw

Jun 17, 2009 6:39:00 AM

If you're like me, you're working on many things at once. You're continually developing, doing research, fixing bugs, helping people, etc. When it comes time to do your status report, how do you remember what all you did this week? When you see a bug that looks a lot like one you fixed two months ago, how do you remember what you did to fix it? The solution is simple, and yet I find many developers don't do it. Take notes. You should take short, but informative, notes as you work, on all the things you work on that day. These notes don't have to read like the next Great Novel. The purpose of the notes is to trigger your memory into remembering what you were doing when you took the note.

A note can be as simple as "9:45am: Spent 15 minutes helping Mary track down an NPE in her service code." That sort of note would be useful for that week's status report, or to remember what you were working on for time tracking purposes. Or the note might be more technical, to help you keep track of the problems you encounter during a project and their solution. "2:10pm: After regenerating the web service client, I get an InvalidNamespaceException when I try to publish the application to the server. Here's the stacktrace…" And then you cut and paste the stack trace. When you finally do figure out the solution, make a note: "4:15pm: Found the solution to the InvalidNamespaceException; I needed to set elementFormDefault="qualified" in the WSDL before generating the client so that every element is fully qualified." You're not trying to put down scintillating prose here, just keep a simple record of what happened.


Now again, if you're like me, you might be saying, "This is a pain." I admit it, it is a pain, but a small one compared to the pain it can alleviate later. The payoff comes when you see an InvalidNamespaceException two months (or two years) later. I absolutely, positively, 100% guarantee this will happen to you (not a guarantee). There will be a nagging feeling in your brain that you've seen this before. "Of course I've seen this before! What did I do?" If you've taken notes, you won't have to rack your brain. Simply search for "InvalidNamespaceException" and the answer will pop up.

I've been taking notes since way back in my former life as a systems administrator. Adminstrators understand the virtue of laziness; but it's a laziness that is only possible because of some up-front effort. Whether it's writing utility classes that wrap complex APIs, or shell scripts that perform some mundane task automatically, or taking notes, it will pay off ten times, a hundred times, in the end.

Some people take notes in notebooks (the old-fashioned paper kind). If that works for you, then great. For me, not so much. First of all, my handwriting when I'm rushed is atrocious. It's like shorthand, but with no rhyme or reason to the symbols. Alien. And obviously, there's no automatic way to search it, and no cutting and pasting. Take notes on that miracle invention, the computer. You can fire up your favorite text editor of choice and go nuts. Whatever that editor is (vi), simply keep a text file that represents the notes for that day, "2009_05_27_notes," or something like that. When you need to search for that InvalidNamespaceException, just run a search in your notes directory, something like:

grep InvalidNamespaceException --color --recursive --context 2 --line-number notes *

This is really all you need. There are some specialized note-taking tools that work well, however. When I'm in a Microsoft Windows environment, the Microsoft OneNote program is excellent. It has facilities for putting notes in folders, within projects, as you would expect; but it adds things like being able take screen shots, and then index the text in that screen shot so that you can search on it later. That's useful for when an error message pops up in a dialog box and you need to capture its contents. You can highlight text, tag paragraphs, etc. etc. But for 95% of my professional life, I've just been grepping text files, and like I said, that's really all you need. The important thing is that you capture the information.

One more thing. Be sure to back up your note files! There's only one thing that's worse than keeping notes, and that's learning to rely on keeping notes, and then losing them all. I have used notes that are seven years old to solve a problem. They will quickly become one of the most valuable tools in your toolbox. No, they will be the most valuable tool in your toolbox. The most valuable knowledge of your career doesn't come from books, webpages, or conferences, but from the contents of your previous experience. Take notes!

Topics: Agile and Development, Perspective