I’ve found a bug in your code…

Have you ever been in the following situation; where it has been 8 months since you worked on a piece of code, you have moved onto bigger and better things. Different features, a different project and horror of horrors you get an email saying someones has found a bug in your code. It was a reasonably complicated feature you worked on, it took a lot for you to get it to the state it was in, and perhaps it wasn’t as well unit tested as it should of been, or perhaps worst yet, it’s unit tested out the back end and every test is passing?

I’ve been in this kind of situation. I haven’t been working professionally as a software developer for that long, yet I have had it happen to me on at least 5 or 6 different occiasians. The first few times it was a bit of a disaster. Not because the issue was big, but it was a blow to my confidence. Lets move on from that though. As I got my hands on larger and larger features it was a much bigger deal. All that valuable information was stored in the far reaches of my brain and noone where else. When the last commit message to a piece of code has your name on it you better get ready.

This is why I take notes when I work. I take very meticulous notes in fact. Would it surprise to know that I can tell you what I was doing, in a reasonable amount of detail, for every single day of my professional software development career? I can tell you about defects I’ve worked on, how I felt about developing certain software features. The rational I choose when it came to certain decisions I made about certain features. Why I started something, but didn’t go back to it. Exactly when I learnt about a really useful feature of a framework I was working with. I can give you references to all manor of Stack Overflow questions and answers I’ve used during developing a feature or working on a defect.

Check yourself, before you wreck yourself

I believe in writing everyday. I believe in this principal not to become a better writer and communicator (though that would be a side effect). I do it to cover my back. It’s the case that the software and documentation processes I follow are not detailed. Well… they are detailed from certain perspectives. But they are in fact not detailed from a personal perspective. Take anyone you work with, take a feature they have worked on. If there isn’t a sentence in a document describing why they choose to do (x) instead of (y), it’s likely they don’t remember and never will. I know that is the case for me when it came to college projects and the very early days of my career.

It’s also useful from a administrative perspective. Where I work I’m expected to fill out a monthly time sheet. I know when I was in or out sick, I know when I was working on features for one project versus another. I know whos time I took up and when. I know how many meetings I go to and what was discussed and decided there. This is highly valuable information for my employer. They can be sure I am billing the right projects for the right amount of time every month.

When you can’t learn in the open

From time to time I’ve heard people talking about the value of “learning in the open”. Sometimes that is not possible. I could not blog about the intimate details of the technologies I deal with daily. It’s just not possible, because it’s all propriety technology. It is the IP of the company I work for not mine. As such the kind of details I am keeping, though they could never be used to engineer or reverse engineer any of their tools is still considered sensitive and I take a personal and professional responsibility in never revealing those details publicly.

When and why did I started doing this?

I started doing meticulous note taking, in the way in which I do it today, back in 2008. While at college I had a lecturer who insisted we completing a weekly “Learning Journal” for his subject “Industrial Automation”. To be frank, it was a bit of a pain at the time. The questions were broad and required a great deal of effort to come up with adequate answers to complete them. The following were the different question heading we’d have to complete week to week:

• Summarise the work that you as an individual did this week (~200 words)
• What are the some of the most significant ideas that you have learnt this week (~3 sentences on each)?
• Take any one of the learning outcomes and discuss how your work & learning is related to that learning outcome (~100 words)
• How has your work & learning contribute to the project that you are working on?
• What aspects are causing you the most difficulty at the moment?
• What would you do differently if you were to repeat this weeks work?

But I’ll tell you right now, I can tell you more about his subject then any of the rest of the subjects from that time combined… and when it came to writing a final report, it was a breeze! The level of detail required from us, and the level of introspection around what we were learning would carve that knowledge deep into my synapses of your brain. And ultimately it was a fantastic resource.

I did a thought masters in the same college and had the same lecture for a project. Again, the learning journal was a requirement of my output. And once again it was an immense help when it came to understanding what I was working on (deep introspection) and a life saver when writing the final dissertation.

What does my note taking work flow look like?

I have three tools in my arsenal when it comes to note taking:

• A pen/pencil
• An A4 pad
• RedNotebook written by Jendrik Seipp

I think digital notes are very important. Being able search, my brain as such, is a highly value ability. However, I do not have or bring a laptop or tablet with me into a meetings or when formulating ideas. I think that pen and paper are faster much more valuable when it comes to getting ideas out my head.

The note taking format that I use is a variation on the Cornell method.

It is basically identical to the Cornell system except I put the points/questions column on the right hand side instead of the left.

An important element of my note taking method and the one I recommend you adopt even if you don’t do any of the rest of what I describe in this article is to date and time stamp every page of writing you do. It’s a frustrating experience (for me at least) to go over older note and not know when I wrote them. I get a great sense of enjoyment seeing my progress as an engineer and developer from reviewing my notes, and not having those dates hampers my ability to do that effectively.

Digitizing

Once I finish working on an idea, or come out of a meeting I proceed to digitize my notes. I don’t go overboard. I usually just take the main points and tasks/summary and place them into my note taking application. RedNotebook is a desktop journalling tool. It allows me to write a daily log of everything I work on.

In the image there are the main parts of the application; on the left is the the date widget and the tag cloud. In the middle is the main note taking space (formatted in markdown) and on the right you can place tags (very useful for searching).

RedNotebook also supports pre-written blocks of text called templates (they are like code snippets) which you can throw into your current work day when ever you would like. This is a useful feature when it comes to putting notes around meetings into my log (I go to a lot of meetings). I usually tag each day with a high level view on what I’ve worked on then.

At the end of all of this I now have detailed hand written notes, with the most important information in RedNotebook… which is also acting as a form of indexing system for my hand written notes. So when someone comes knocking at my door asking about some feature I’ve worked on. I fire up RNB, start searching, find relevant details there and if not there I know what date to flick to in my binder full of notes.

Lies, Damn Lies and Statistics

I’ve gone to the trouble of doing a bit of graphing for this post. Above I’ve provided a graph with days versus number of words written. As you can see there is a lot of variation, and my average number of words written reflects on the amount of information that I keep. Granted some of it is boiler plate (personal meeting minutes, where I detail who attended and the like).

RedNotebook provides some basic statistical information namely the following table of data which is accurate for my journal as of the 11/December/2014.

Statistic Type	Data
Words	106177
Distinct Words	9442
Edited Days	687
Letters	663692
Days between first and last Entry	978
Average number of Words	154.55
Percentage of edited Days	70.25%

Conclusion

Ultimately what I am saying is, writing is good. Keeping notes is a rewarding and more importantly professional thing to do. And when a process is not extremely granular and you want to avoid “project lore” use a process to keep a track of that information. If you can make that public (within your company, Intranet blogs?) and if not, then maybe consider a personal system like I have.