Using MS Onenote to manage bug and release information

Dan Esparza, April 4, 2012

The problem

Interruptions cause a real problem with lost time during software development. Jeff Atwood summarizes this nicely:

Even adding a single project to your workload is profoundly debilitating by Weinberg’s calculation. You lose 20% of your time. By the time you add a third project to the mix, nearly half your time is wasted in task switching.

As a software developer, I’m constantly trying to avoid getting distracted by production incidents, other bugs, and high priority features that need to get implemented. Don’t get me wrong – I think each of those things is a necessary (evil) part of software development.

The solution: taking notes

We’re already using the computer to program, I figure it makes more sense to take notes on the computer (vs pen and paper). After trying to use Evernote and getting frustrated with the lack of a decent print view or formatting options, I chose MS Onenote and haven’t looked back.

Why Onenote?

My data is easy to organize... need to create to rearrange your notebook pages? Just drag and drop. Need to type notes? Just type anywhere. Need to indent certain pages under others? Just drag to indent.
My data is stored in the filesystem and backed up and sync'd via Dropbox. (Optionally, your data can get sync'd via Skydrive, but I've had bad experiences going this route).
Quickly format text in tables, lists, headings and highlighting
Sometimes ideas are hard to express with words - Easy to use drawing capabilities are built in. Several times I've used Onenote as a virtual whiteboard to share visual ideas with co-workers when screen sharing.
It's easy to spit out a nicely formatted PDF. Something that looks professional with no effort on my part. Something that I can show my boss. This can't be overstated.

Using a template to ease your workflow

Let’s face it: Note taking is tedious. Somewhere after achieving amateur note taker status, you’ll either want to give up or make life much easier for yourself somehow – because taking notes on a bug every time will begin to feel very repetitive or even worse: a waste of time.

Templates make your life easier in MS Onenote.

Before creating a template, think about:

What kinds of items do you find yourself wanting to capture over and over again?
If you were a developer digging through this bug again in 3 months, what helpful information would you want laid out in front of you?

Next, create a note with the appropriate content to prompt you, then save as a template. Finally, use the down arrow by ‘New Page’ to select your new template. It’s just that simple.

Sample template content

My default bug fixing template has the following information in it (or if you already have Onenote, just download and unzip this sample):

Default text in the title to help format it correctly
An overview, with the heading ‘Overview’ and some text to prompt me, like this: “Summarize the issue in plain English. Indicate any connections to other bugs here, and if you’re planning on getting help from specific developers (and what they’re going to help with).”
A ‘related incidents’ section with a table that includes 2 columns: Incident # and Description
Setup notes, with an initial list item that has the following prompt: List anything required to setup the project (IIS setup requirements, .dll references/includes, config changes, environment requirements, etc)
A repro notes section to allow me to include complete steps to reproduce the problem.
A source review section with a table that has the following columns: Item and Found here. This will allow me to specify where certain bits of code are located based on what they do. Your future co-workers will appreciate this.
A source annotation review section. This is where I visit the source annotation (sometimes called ‘blame’) view of the repository to try and determine who last touched the lines of code I’m looking at – and what led them to make those changes. Hopefully they have check-in comments that indicate why they changed the source. The point of this section is not to lay blame but to leave a trail of crumbs. If something is confusing, ask these developers first.
A debugging notes section. Perhaps one of the most important sections. If you have bugs that take several days to work through, the notes you take here will be invaluable. You’ll find that as long as you take reasonable notes, you can set a problem down, enjoy lunch, and pick it back up again with ease – and you’ll know right where you left off.
A new configuration items section. This includes a table with new configuration items and their descriptions.
Finally, I also include a resolution timeline section. This is a table that includes the following rows: Smoke test successful, Code review, and checked-in. Each of these items has a date/time that I fill in when it’s complete. It serves as a record of when certain items are completed, and can be helpful when putting together a status report.

Tips

Create a visual hierarchy based on releases. Also: Create a release information template to use as the top-most tab for a release. It should include important dates for a given release.
Save to PDF and include your notes in emails and bug reporting software. You'll be the envy of your co-workers. (I've actually had QA specifically request the bugs I fix because the notes I take make their life easier)