Jake Worth

• vim

Today, I’d like to dive deeper into a part of my practice: using a persisted text file for jotting things down. You can read the post I’m following up on here.

In this post, I’ll explain the ‘why’ behind this technique, and provide an updated version of it.

Why Use a Scratchpad?

Why use this technique? Here are a few reasons.

📗 I’m a note-taker. The military trains soldiers to always have “something to write on, and something to write with.” When I see somebody in a meeting not taking notes, I wonder if they’re paying attention and how they’re going to remember key details.

It helps me solve hard problems. Programming is hard. Do it long enough and you’re going to face difficult, novel problems. Problems that are unique to your codebase, where there isn’t a Stack Overflow post in the world to help you. When this happens, it’s time to think hard. I get organized by writing down goals, assumptions, unknowns, action items, etc.

It supports pair-programming. Having something to look at when pairing, especially remote, has helped me cut through ambiguity. It reorients the conversation from “this is what I think, this is what you think” to shared ideas we are writing down.

It prevents backsliding. Writing cements things. As I wrote in All My Best Debugging Tips, something I find distracting is backsliding. You’re zeroing in on the bug in the frontend, you lose focus or bring in a pair who isn’t up to speed, and suddenly you’re asking “maybe this is a database issue?” I want to move forward, not retread dismissed ideas. Writing supports this.

You can cut-and-paste, search, and share. Using a Vim buffer lets me copy-and-paste errors and code snippets freely, search them, and share them.

It’s disposable. When I’m done with the scratchpad, I can close it. Or, I can clean it up and turn it into a pull request description, ticket, or documentation for a knowledge repository. That’s a valuable way to preserve the context I’ve gained.

To summarize, I:

• Open the file whenever
• Use it to practice note-taking
• Use it to solve hard problems
• Use it to align with a remote pair
• Use it to prevent backsliding
• Paste into it, search it, share it
• Throw it away or keep it

There’s a saying in programming: “Weeks of coding can save you hours of planning.” The scratchpad helps me be more intentional about my work.

The Scratchpad

Since documenting this technique, I’ve refined it: now, instead of a buffer file in the root directory, I create a file in each project directory called .scratch.

" ~/.vimrc

" Open a buffer for note-taking
nnoremap <leader>q :e .scratch<cr>i<cr>

Why the rename? I like dotfiles. Directory explorers tend to ignore them.

My scratchpad is globally ignored in Git via a .cvsignore:

# ~/.gitconfig

[core]
	excludesfile = ~/.cvsignore

With this approach, I have a unique file in each directory and my notes stay isolated. Thanks to Jack Christensen for helping me iterate this.

For those who want to learn more, my dotfiles are open-source.

Thanks to Chris Erin for always pushing our pairing toward documentation and Adam Young for inspiring this follow-up.

What are your thoughts on this? Let me know!