Every growing professional should have a notebook of some kind—that very personal, permanent collection of useful artifacts related to your trade. The programmer’s notebook is inherently non-physical.
It would be nice if we could keep everything in a stack of paper bound with metal, but that isn’t our medium. The programmer’s notebook must allow for instant recall and painless entry. The programmer’s notebook is our personal Google; our outboard brain. Let’s dissect this a bit.
Data and Use Types
The programmer’s notebook doesn’t have just one type of data. I’ll be highlighting a few:
Bookmarks
Text Notes
Documentation
Files
The programmer’s notebook is also a system, and every system has methods of input and output.
Input is the method of getting data into your system. For text notes, that is a text editor. Too many input systems can lead to confusion. When we encounter something we want to save, we shouldn’t have to mentally vie with eight different ways to store it.
Output is how we retrieve data from the system. For bookmarks, that is Pinboard’s website. Getting data out of your system is of utmost importance. Without the knowledge that we can retrieve anything at a moment’s notice, the system breaks down. We must be able to trust the system as much as we trust Google.
Bookmarks
I use Pinboard to track my bookmarks. I also pay for the $25/year archiving service so I can run full-text searches.
Input
I use the Pinboard bookmarklet to add bookmarks to Pinboard. I do this because almost none of the third-party apps show suggested tags for the site being saved. Without tags, bookmarks can be a pain to find, even with full-text search.
Output
I use the Pinboard workflow for Alfred for quick, small searches. For in-depth searches, I use Delish. I find that the visual preview of the website in Delish helps enormously when hunting an elusive bookmark. On iOS I use Pinbook to view bookmarks on the go.
Text Notes
Plain text Markdown files in Dropbox. Inspired by Merlin Mann and Brett Terpstra I store everything in plain text files for searchability and portability.
Input
I create all of my notes using nvAlt. The mix of instant search and instant file creation work magically for me. Anything I edit for longer than a few seconds gets opened (using ⌘+⇧+E) in MacVim. I prefer MacVim to terminal Vim for writing prose due to its anti-aliased font rendering and interaction with OS X Services.
On iOS I use Drafts to append to existing notes. I have many notes in my Dropbox notes folder to which I append using the Dropbox actions Drafts provides. Write a couple sentences, tap a button, and I’ve got a time-stamped note appended. In the rare case that I create a new note file on iOS, I use Byword, which has a wonderful Markdown keyboard and automatic completion.
Output
For search on Mac I also use nvAlt. It is the fastest and easiest to launch application for this purpose. I always have it running since it has almost no memory footprint. I preview what I write in Markdown on the Mac using Marked. I open the preview from MacVim using vim-marked.
On iOS, I use WriteRoom for full-text search of my notes folder from Dropbox. WriteRoom is the only app I’ve found that handles full-text search of all text files in a Dropbox folder gracefully. Most require the syncing of individual files before performing the search.
Documentation
Documentation is any third-party source of information you use constantly while programming. Sometimes a link in Pinboard is all you need. Other times it’s a living document in a Markdown file in Dropbox.
Input
I love Dash.app for the Mac. It stores documentation sets for most programming languages and popular frameworks locally.
For anything that I can’t look up in Dash, I maintain a checkout_code folder in which I keep clones of all open-source repositories I am using. I make it a habit to clone everything locally once I reference the documentation more than a few times. Thanks to GitHub Pages, most open-source projects I use have Git-cloneable websites.
Output
Dash’s search is instant, and it works without an internet connection. Searches can be scoped to a programming language or framework of choice. However, I find that I use global searches frequently as I often need the documentation for similarly named things at the same time. For example, a search for date will show me the class definitions for a Date object in Ruby and JavaScript.
For searching my checkout_code folder, I use The Silver Searcher. Normally, I have an iTerm window open with a tab for each open-source project I’m using. I’ve got Vim open in each of those tabs, and I use NERDTree to scope my searches and Ag.vim to search for documentation using The Silver Searcher.
Files
Sometimes programmers have to shovel around blobs of binary data. Pictures of buggy apps and the occasional Excel document grace my magnetic platters. For a long time, I’ve been using CloudApp to share pictures and small bits of syntax-highlighted code. Recently, I’ve been using Dropbox more frequently due to its support for larger files. However, I still prefer CloudApp since it feels messy to tie URLs on the web to arbitrary locations on my file system.
Input
Sadly, I don’t have an incredible workflow for moving files around on my system. I experimented with Pathfinder, but I did not like its non-native feeling.
I store most of my files in Dropbox using a simple folder hierarchy. I almost never search for files explicitly. When I download something I use the Alfred Recent Downloads workflow to access the file. Files found using that Alfred workflow can be dragged into other windows or opened immediately.
Output
I use the menu bar icon provided by CloudApp for Mac to drag, drop, and share images and small files. Files I upload to CloudApp I immediately share using the link. I sometimes browse those files on my iPhone using CloudApp.
Conclusion
Those are the core pieces of my personal programmer’s notebook. Of course, I’ve got tons more fiddly bits that make up my workflow, but those may warrant another post down the road. I’d encourage you to continually evolve your own notebook system and find what works best for you. Be sure to share with the rest of us when you find new great tools!
