Take note: Take notes!

June 17th, 2009 Bill Shaw, Consultant  (email the author)

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!

Be Sociable, Share!

Entry Filed under: Agile and Development

25 Comments Add your own

  • 1. wwwald  |  June 19th, 2009 at 1:53 am

    I couldn’t agree more. I’ve been taking notes like this since a couple of years and they have been a real time-saver.

    I have never used OneNote, but I’m eager to suggest WikidPad as a great alternative: open source, actively developed, no-nonsense, written in Python and customizable to the bone.

  • 2. Ren  |  June 19th, 2009 at 6:30 am

    I’ve been taking handwritten notes for years but mostly for time tracking purposes. Lately I’ve been using them to also compile a knowledgebase or problems and solution that I can refer back to. I’ve started using Google Notes so that I can access notes from home or add from home to access at work.

  • 3. iwinux  |  June 19th, 2009 at 7:21 am

    Sadly, the firefox extension of google notes is no longer supported by google team…

  • 4. David Leal  |  June 19th, 2009 at 10:37 am

    I find the Harvest Co-op app (http://coopapp.com) to be ideal for this. It is like twitter for teams, and if you use Harvest for time tracking Co-op allows you to track time, too, by linking to your harvest account. Handy.

    Harvest is at http://harvestapp.com

    I don’t have anything to do with Harvest, btw, just a happy customer.

    David

  • 5. Siva  |  June 19th, 2009 at 11:20 am

    I ll try to start doing that now on. I ve been using Evernote app for taking some misc notes. I found it quite good. The best part of it is you get access to your notes anywhere (ofcourse, you should be having internet connection)

  • 6. Lee Borio  |  June 19th, 2009 at 11:47 am

    I started seriously taking notes when I switched from networking to programming in 2005. It took a while to find a tool I liked but I came across Confluence and have been very happy with it since then. I’m sure there are a ton of other tools, for me I has to be a wiki and Confluence is easy to setup/configure/run and has a pretty decent set of features. They have a FREE personal license.

  • 7. popurls.com // popular to&hellip  |  June 19th, 2009 at 11:59 am

    popurls.com // popular today…

    story has entered the popular today section on popurls.com…

  • 8. Iceman  |  June 19th, 2009 at 12:20 pm

    Emacs Notes mode used to be my tool of choice for this. Its automatic indexing of notes on the same topic was extremely useful – I could work in a stream-of-consciousness desultory mode and have the luxury of having my thoughts organized for me automatically.
    These days, I tend to use Emacs org-mode more. No automatic indexing, but lots of other features – TODO lists (auto-organized), tables, etc. I shudder to think what my productivity would be without notes ….

  • 9. John Haugeland  |  June 19th, 2009 at 12:56 pm

    You should consider learning CMU’s Personal Software Process. You’re starting out in a good direction, but there’s a whole lot more to be derived here.

  • 10. jm  |  June 19th, 2009 at 12:56 pm

    I’ve been taking notes like this for about three years now and I have to admit I still haven’t got it perfected yet. In the beginning I took verbose notes detailing everything I did, but after a few months it became unwieldy to go back and manually search through a hundred pages of notes trying to remember where I might find that detail I knew I had seen.
    It was a little better when I finally started doing everything on the computer, but invariably it seemed like I was recording a lot of information that I never ever needed again, and spending a lot of time doing so, and when I did need some tidbit of data it wound up being the one thing during the day in question that I had considered unimportant or for whatever reason had not documented.
    I’ve sort of had to resign myself to simply keeping a whiteboard with items that really stand out, such as stupid bugs that I fight for half the day only to find there was some tangential solution that really should be unrelated to what I am doing (“oh! my program isn’t working because the router needs to be power cycled!”).

  • 11. Ben Northrop  |  June 19th, 2009 at 1:41 pm

    I’ve been using OneNote for a little while now for tracking daily status for stand-ups, and it’s pretty much what I need – good WYSIWYG editor, search, groups, etc.

    Picking the right tool up-front seems pretty key, cause once you have a few months of notes written, it’s tough to switch.

    Good post.

  • 12. pitnick  |  June 19th, 2009 at 2:35 pm

    “9:45am: Spent 15 minutes helping Mary track down an NPE in her service code.”
    I try an even shorter style:
    “20090101 Mary NPE service code /src/core/npe.c load_handle()”
    Gives an instant recollection of what I did _exactly_

    Document the catch / gotcha. That’s the crux.

  • 13. gregor  |  June 19th, 2009 at 8:21 pm

    I’ve been doing this both at home for personal projects and at work for a few years now..
    I add a small bit of structure with -tags- in my daily text file, so that each one has
    -hours-
    to record when I came and went
    -workplan-
    for what I’m trying to do, and what got done each day
    -todo-
    for all the interruptions and support calls I field during the day so I can get my mental stack context back
    -projectspecific-
    individual notes for each project/component

    my editor supports little macros so i can findtag tag x to grab the last x notes on a topic in reverse descending order. this is great at home, where i jump from interest to interst and need bookmarks to remember what i was doing.
    At work, grepping is more useful, but then I can move around in the time stream.
    I also have lots of links to relevant wiki pages in our team wiki, cause iideally good reference and change info gets into there.

    Being responsible for a large legacy system, the daybook is a great place to put a set of queries when I’m trying to untangle some behaviour, that I can then go back to next time I need to do the same thing, and eventaully if necc I can turn it either into a refactoring job for the system, or a procedure to resolve a problem documented in the team wiki.

  • 14. Calvin Spealman  |  June 19th, 2009 at 9:48 pm

    I’ve been trying to do this for a while. Getting into the habit is the hardest part. I tried a paper notebook a week or two, and then made a Google Docs Spreadsheet with a single entry form. It adds a timestamp to the spreadsheet automatically, and I’ve got it in my toolbar and on my phone home screen, so I can make entries anywhere.

  • 15. David Johnson  |  June 20th, 2009 at 6:51 am

    Thanks for the reminder and validation. I am the sole note-taker in the group which means that I get asked the questions about what we did and when. I use Evernote (non-synced) and record daily activities. I also set up a personal wiki on my server so that other people can access notes that I have taken. I have to use a windows machine at work so I use screwturn wiki (it was tough to get that unblocked!)

    Also, time tracking with Rachota is a breeze! I have turned 2 of my 3 co-workers on to it.

    Thanks for a great read.

  • 16. Hal Helms  |  June 20th, 2009 at 12:31 pm

    You might like Evernote. I switched from OneNote recently and find it very useful for making the notes you’re talking about.

  • 17. Daniel Furrer  |  June 21st, 2009 at 10:05 am

    I agree that taking notes is a good idea and I’ve been doing so when working on projects for the last couple of years. Some ideas in this post and the comments are highly useful.

    Personally I’m still using a paper-journal however. It allows me to quickly draw stuff and put notes in there even when in a meeting or sketch something during a discussion with a colleague. I found putting the date for each day fine grained enough and whenever I have something that I need to get back to I put a checkbox [_] in front of it so that I can check it when I have done that [x].

    Daniel

  • 18. Jeff Howell  |  June 24th, 2009 at 9:04 am

    On the OS X side, I have been using Journler (http://journler.com). Good feature set and easy searching.

    The searching would be nicer if it worked with the shelf full of paper notebooks!

  • 19. My daily readings 07/03/2&hellip  |  July 3rd, 2009 at 6:45 am

    [...] Take note: Take notes! | Summa Blog [...]

  • 20. Axel Rauschmayer  |  July 10th, 2009 at 4:24 pm

    If I may plug my own work: Hyena is great for keeping small tagged notes (see “quick notes” in the manual). It does have a learning curve, but it’s free, so you can find out if it suits your taste.

  • 21. Ken Liu  |  July 12th, 2009 at 7:50 pm

    At my workplace, developers are encouraged to use JIRA (our bug tracking system) to keep notes on any issues they are working on. This has the added advantage of helping other members of the team find out about anything that was done to fix a particular bug. It’s also helpful if you need someone else to pick up where you left off.

    It is a little more work to write notes that other people can understand, but it is useful in the long run.

  • 22. Taking Notes and Tweets &&hellip  |  July 13th, 2009 at 5:47 am

    [...] to be useful in the long term. We never know when something is useful. One guy, Bill Shaw, has this point to make: Now again, if you’re like me, you might be saying, “This is a pain.” I admit it, it is a [...]

  • 23. Javier  |  July 15th, 2009 at 2:01 pm

    “The slightest ink is better than the brightest mind”

  • 24. Chris-Bierig  |  July 29th, 2009 at 4:17 pm

    Great idea, but will this work over the long run?

  • 25. macpro  |  December 27th, 2013 at 10:17 am

    wow.

Leave a Comment

Required

Required, hidden


5 + two =

Some HTML allowed:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Trackback this post  |  Subscribe to the comments via RSS Feed

© 2010-2014 Summa All Rights Reserved