How Note Taking Makes Me a Better Developer

I suspect almost everyone reading this blog has taken notes before, especially in a classroom setting. As my career has progressed from college student to professional developer and finally to a managing partner, I’ve also found that note taking is useful while developing software.

In fact, note taking is a transferable skill—one of those abilities that’s helpful across different areas of life, whether socially, professionally, or at school. In this blog post, I’ll describe some ways I’ve applied note taking to software development (specifically, programming).

Spinning Up a New Project

At the start of a new project, or when on-boarding someone into an existing codebase, it’s very common to carry out one-off tasks around project setup. Some examples include acquiring a domain name, hosting the system, acquiring SSL certificate(s), constructing a build pipeline, connecting the software with a continuous integration server, etc.

Taking note of what was done and why it was done at each step contributes to the long-term health of the project in three key ways:

• It provides documentation for new developers who ramp into the project.
• It can be used to create documentation that lives on after active development ceases.
• It acts as a natural gut-check for activities. As you take the notes, you will ask yourself, “Does this make sense?”

I followed the above advice a couple of years back when setting up continuous integration for an iOS application, and I wrote about the process of setting up CircleCI in a blog post. Half a year after writing that post, Apple updated Xcode, and CI broke. Because I had taken notes, the developers on that project were able to retrace my steps, find the problem, and correct it.

Debugging and Optimizing

There have been times in my career as a developer that I’ve encountered bugs that have been hard to solve—the types of bugs that are entwined with other issues and leave you feeling like you’re chasing your tail after hours of debugging and testing. To avoid this problem, I’ve used a pseudo-scientific method:

1. Formulate a plan of possible fixes, or ways to identify the root cause (your hypothesis).
2. Identify and isolate one variable to test, or write some code to try to solve the problem (experiment). Take notes!
3. Tweak your hypothesis based on your experiment outcomes.
4. Repeat.

In the above process, the key for me was documenting results via notes as I went along. Taking notes protected me from going down paths that I had already tried, and it helped me stay focused on the initial hypothesis. In case I did get stuck, I had documentation showing what I had tried. This made it much easier to communicate the problem to another person if I needed to ask for help.

Helpful Tooling

The information I capture as notes falls into three categories:

1. Commands or actions I have taken: This could be code, a terminal command, a setting in an IDE, etc.
2. Textual output of the commands
3. Screenshots

For terminal commands, there are a few tools that come standard on *NIX systems. For all *NIX command shells, fc can be used to edit and re-execute commands. It also has a handy listing feature that will display past commands, as follows:

] fc -ln -5
	 bundle install
	 ls
	 ruby generate_hours.rb 2018-10-1 2018-12-31
	 open output.csv
	 open .

The above command prints the last five commands in the shell. It’s useful for capturing the steps that were taken from the command line. Another option that I find helpful is the OS X commands pbcopy and pbpaste (Linux users can check out xsel). pbcopy takes the standard input and places it in the specified pasteboard. By default, the “standard pasteboard” is the clipboard. Piping output of a command into pbcopy will send it to the clipboard:

] ls -la | pbcopy
johnfisher@Robin-Hood:~/fun_projects/smuggler ruby-2.3.4
]

The above command sent the results of the command, ls -la to the clipboard. Now you can paste it into your notes for reference! I like to use a cloud-synced tool that supports images, such as Notes or Google docs. In case you wanted to see what the output actually was, use pbpaste to dump it to stdout:

] pbpaste
total 88
drwxr-xr-x@ 11 johnfisher  staff    352 Aug 27  2015 .
drwxr-xr-x  33 johnfisher  staff   1056 Oct 22 11:11 ..
-rw-r--r--@  1 johnfisher  staff   6148 Aug 27  2015 .DS_Store
-rwxr-xr-x@  1 johnfisher  staff   4018 Aug 18  2013 README.md
-rwxr-xr-x@  1 johnfisher  staff  15856 Aug 17  2013 names.txt
drwxr-xr-x@  4 johnfisher  staff    128 Aug 27  2015 src
drwxr-xr-x@  4 johnfisher  staff    128 Aug 27  2015 test
-rwxr-xr-x@  1 johnfisher  staff    521 Aug 16  2013 test1.txt
-rwxr-xr-x@  1 johnfisher  staff    217 Aug 16  2013 test2.txt
-rwxr-xr-x@  1 johnfisher  staff     78 Aug 17  2013 test3.txt
-rwxr-xr-x@  1 johnfisher  staff   1387 Aug 18  2013 test4.txt

Screenshots are easy in OS X, but the keyboard shortcuts are a little complex. Prior to Mojave, I preferred to use command-control-shift-4, which allows you to click and drag to select a portion of the screen you wish to capture to the clipboard. This is great for grabbing parts of the screen, and I like to paste them in-line into my notes.

OS X Mojave released an improved, more interactive tool for screenshots, and it also has a recording feature. After taking a screenshot, it displays the image in the lower-right portion of the screen, allowing you to click on it and add markup. This is really convenient because it saves a step of pasting the image into an editing program, like Preview.

If you’ve taken technical notes during development, I’d love to hear what tools and techniques you’ve used in the comments.