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:
- Formulate a plan of possible fixes, or ways to identify the root cause (your hypothesis).
- Identify and isolate one variable to test, or write some code to try to solve the problem (experiment). Take notes!
- Tweak your hypothesis based on your experiment outcomes.
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.
The information I capture as notes falls into three categories:
- Commands or actions I have taken: This could be code, a terminal command, a setting in an IDE, etc.
- Textual output of the commands
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
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.
I also found taking notes has a positive psycological impact on the developer themself, especially during debugging. It gives a feeling of progress even if the solution has not been found, yet.
In terms of tools I use Windows Shift + Win + S screenshots. VSCode for markdown (excellent for code syntax highlighting). Markdown PDF VSCode extension is very useful to rework notes into a document and email them. Code Spell Checker VSCode extension come handy as well.
Interesting point on the psychological effect of taking screenshots feeling like progress. I hadn’t thought of that, but it rings true. Thank you for the comment, Oren!
Comments are closed.