I occasionally like to dip my toes into the world of productivity techniques, something I think worth doing while keeping in mind that you can spend all day researching productivity while getting nothing done. I’ve found that there is a very useful productivity program that comes as part of my favorite programming text editor, that being Org Mode for Emacs. As you can expect from an Emacs application, the learning curve will require you to lace up your boots and be ready for an uphill march, but now that I’ve progressed far enough to be productive with it, I’m glad I made the trek.
What’s great about it is its flexibility: an Org Mode file can be used as a Kanban board, a time tracker, or an outline for a blog post. Here I will be discussing a particular application for Org Mode that I have found useful, although there is no reason you couldn’t use Markdown, HTML or whatever your preferred markup language is for the same purpose.
But first, a little story.
The Mystery of the Failed POST Request
I occasionally work on WordPress sites as a side-hustle of sorts. One of the sites I work on, which I inherited from previous developers, uses a plugin called Divi (I’m not affiliated with them in any way and am not plugging this plugin, but there’s no reason to keep it a secret), which provides a nice drag-and-drop configuration interface for laying out a WordPress site’s pages and posts.
One day while working on a page, I found that for some reason, I could not save my changes. The error message was as opaque as you’d expect, so I did what I’ve done many times as a web developer: I popped open dev tools and took a look at the Network tab. This was not terribly enlightening, but did tip me off that GoDaddy’s hosting infrastructure did not like the look of the POST request. After a good bit of trial and error, I figured out that the issue was with some text that was followed by a pair of parenthesis, which GoDaddy must have viewed as a possible XSS attack. I found a work-around, got the page saved and life went on.
The point of the story is this: even though this site was built with a framework meant to make it easy for someone without web development knowledge to put together a decent-looking site, yet a certain combination of technologies communicating across separate systems conspired to create a situation that required knowledge of HTTP requests, Cross-Site Scripting vulnerabilities, and the functioning of Intrusion Detection Systems to work around.
This is not an uncommon situation to find oneself in as a developer: you can have years of familiarity with a set of technologies, and then some very specific combination of factors causes an issue that you have never seen before and which requires all of your debugging skills to remedy.
Sometimes these unprecedented problems are the outcome of circumstances so specific that they never come up again. Others are common enough that you learn to recognize them immediately, such as those errors you get used to seeing while working with a certain language; Java’s null pointer exceptions for example. Then there is a hazy twilight world of errors that happen repeatedly, but infrequently enough that when they do reappear, you forgot how you handled it last time.
The Many Lives of Code
Some code is written to support a long running application, and is supported with tests and reviewed by peers before it is ever run in the intended environment. Some code is only needed right at the moment it is written, such as any command you run in a terminal session. Some code is downloaded by millions of people all over the world, some never leaves the computer it was written on. Some code sticks around for years, some is discarded as soon as it is run.
There is a certain neighborhood in this multi-dimensional space of code types that contains snippets of no more than a few lines of code that does something specific but useful. While copy+paste programming is naturally discouraged, nevertheless there are those snippets of code that you find yourself repeatedly copying from a previous session, making a few edits and running again. It could be a Bash one-liner that runs a tool that generates code from a template, or a SQL command that gets the metadata about a table.
An L1 Cache For Your Mind
The human mind is good at organizing information by association, a skill very useful to knowledge workers such as software developers who employ thousands of individual pieces of information in their daily work, more than could ever be stored in a single head. Because you cannot simply memorize the entire Go standard library, you need to know how to track down the documentation for the package you need to work with. Google is your friend here, and your browser can help with bookmarks and search completion if it is information you have accessed before. But the process of hunting down information with web search can be laborious, especially if all you have to go on is the kind of obscure error message mentioned above.
This process of digging up of a specific piece of information by following hints provided by memory is a common occurrence in my own experience as a developer, and I have to assume is not foreign to the experience of others. What you want here is an L1 cache for your mind, a place to store information that you have accessed before but not often enough to become part of the muscle memory in your fingers.
DONT_PANIC.org
Douglas Adams tells us that The Hitchhiker’s Guide to the Galaxy—the fictional book mentioned in the factual book of the same name—has the words “Don’t Panic” on the cover in large, friendly letters. I occasionally find myself in need of this advice, and the occasion is sometimes brought about when looking at an error message I know I have seen before, but cannot remember how to handle. It is for this kind of situation that I started keeping snippets of useful code in a “Don’t Panic” file.
The usual name for this sort of thing is a “cheatsheet,” but because it stores the kind of code that I need in those situations where I realize that I should know how to handle the situation, but can’t remember what the answer is, and don’t want to repeat the process of finding it, I like to name it DONT_PANIC.org. This file is specific to a project, as the set of technologies that are combined in particular project, from programming languages to frameworks to libraries, databases and servers and operating system, determine the set of semi-frequent tasks you will need to perform during its lifetime.
So there it is, my personal piece of productivity advice: keep a cheat sheet for each project to handle these kinds of situations and keep your cool. As mentioned above, Org Mode is my preferred solution for this kind of thing, being easily searchable and supporting embedding and running code, but the principle is the same regardless of implementation.