Tip: Create Your Own "Quick References"

2022-01-22

In software development, and in life, there are a lot of things you have to keep in your head. From different programming language syntax quirks, to keeping your goals in mind, to the steps to deploy a project (if it's done manually). We've got more complex information and details swimming around in our heads than ever.

That's why I'm a big proponent of recording that information and getting it out of your head. Why limit yourself to your memory which is unreliable when recording and retrieving information is easier than ever?

Many people take some version of notes to keep things out of their head, however, I suggest that people also keep a separate "quick references" section separate from their "general notes". While general notes are great for writing quickly and messily, finding a particular piece of information in a large amount of notes can be inconvenient. Having a separate section for curated information where finding and reading the information is prioritized can be helpful.

What to use quick references for

Cheat Sheets

The most common and useful kind is the "cheat sheet". Random collections of things that you just can't seem to remember and you have to keep looking up over and over again. For example, there are so many command line tools with single character flags that are difficult to memorize. They often have man pages, however you often just want a tiny bit of information in a very long document and they're not always easy to understand. Whenever I find myself Googling for the same StackOverflow answer over and over again, I know that it's time to add that bit of information to a cheat sheet.

Goals

A lot of us create goals, however we're not always in the right headspace to prioritize them when deciding how to use your time. If those goals are written somewhere that's not prominent, then those notes and goals are not being very helpful. However, if they are accessible and you can remind yourself of your priorities easily, then they are more useful. Also, if you're forced to curate the ones you reference most, it helps force you to prioritize them.

Manual processes

Processes that are usually the same with lots of steps can be difficult to remember, especially if you have to do the process again after a long hiatus. I try to automate things like build processes, even if it's just with a quick script, but sometimes it's not practical to automate right at that moment. Creating a quick reference is the next best thing. If you get around to automating it, you can use the quick reference as a basis.

Advice for creating and maintaining quick references

Most of all, make sure it's quick and convenient to find information. Most of the other advice I have is just how to make things quick and convenient. You'll probably have other ideas for your setup as well.
Make sure it's Curated. The quick references should be living documents. While quick references are weighted more towards reading than general notes and less towards writing, it should still be relatively easy to add to or modify them. Add to them when you encounter something to remember, remove something when you have it internalized, improve readability, etc.
As emphasized already, make sure it's readable. Curation can help keep the documents short and to the point. Make sure the information is written in a clear but to the point way and is edited unlike most general notes. Potentially also try to use other tools to make it look more presentable or improve the layout. Text or Markdown files are fine, but generating HTML with a script or automatically with Pandoc or using a personal wiki like tiddlywiki can help significantly with layout and readability.
Even for commonly used tools like programming languages, I recommend keeping your own cheat sheets rather than completely relying on other people's cheat sheets. You don't want stuff that you'll never use cluttering up what you reference, and if you add to your references as you need information then they will only be filled with stuff you actually use. Other people's cheat sheets can still be useful for getting ideas of things to add to your own cheat sheets though.
I've found adding a section for things to "experiment" with useful. Maybe that's a new programming language feature, something new to add to your routine, etc. Those things you always intend to try out but never actually get around to it. Make sure to have a manageable amount of things to try out at once and remove things that turn out not to be helpful though.
Make sure to share the quick references you think other people will find useful. While I encourage making everyone to make their own quick references, you can often find handy things in other people's cheat sheets to add to your own, so making yours available to other people can be helpful as well. There's not much of a downside and making it available is generally pretty easy. I've made mine available at the quick references page. It's also often helpful to add to a project's documentation, although you'll want to focus on making your quick references easy to understand for yourself before being understandable to a wider audience.

Hopefully you'll find quick references and this advice useful! I'll add some more of my own quick references over time as examples and for you to use parts of them in your own quick references.