How to Cultivate Your Cheat Sheet

A battle-tested up-to-date super helpful cheat sheet is a huge asset in an engineering team. The problem is that like startups, children to antivaxxers and my sense of humor, most cheat sheets never actually reach maturity.

The fundamental issue is this - if there’s nothing in the cheat sheet you don’t already know, you’ll never use it. If you never use it, you don’t even know what’s in it and if you don’t know that, you won’t point others to it. No one else will contribute and so it’ll die.

Sometimes cheat sheets prevail by having their owner be their champion: the owner adds all the entries and keeps everything in tip top shape, updating, trimming, and keeping a close eye on things.

But I can’t be that champion. I’m way too lazy. And my teammates won’t bother adding entries to an empty or otherwise unuseful-to-them cheat sheet. So what do we do?

Getting Started

Enter our hero: the new person on the team.

The beautiful thing about new teammates is that they know nothing. Well, they know nothing about your team’s particular way of doing things, which is the sweet golden nugget that every good cheat sheet is built upon.

So my strategy is this: whenever someone asks me how to do something, I sit with them and help as much as I can, and very politely ask that they document what they did in the cheat sheet. This is beneficial in so many ways:

• They now know there’s a cheat sheet and how to access it, so that’s another tool in their belt.
• They now know how to edit the cheat sheet, and have less friction doing so again, increasing the usefulness of the cheat sheet.
• The next teammate to join will have more resources to ramp up in the team and the teammate mentoring them will have to spend less time explaining menial tasks and more time for deep discussions and project-specific guidance.
• Now I know there’s useful information in the cheat sheet and will also turn to it when I need to.
• Eventually the cheat sheet is so useful, the other jaded teammate will use it themselves.

Helping it Grow

Once you’ve reached critical mass, the rest is easy. But I still have a few more tips for maintaining participation from the rest of your team. The golden rule here is keep friction as low as possible:

Don’t nitpick: if a teammate sends you an entry to approve, hold back only if there are factual errors. After their entry is in, feel free to fix typos, clear up some phrasing and adjust the formatting. Keep their friction to a minimum.

Go easy on the structure: Categories and menus and order are great, but maintaining taxonomy is hard. Let others just add their entries to the bottom and either sort it out later, or keep it that way.

Optimize for copy and paste: It’s great to explain the rationale of how something works, but cheat sheets are mainly useful for repeated tasks that are easy to forget. For programming, this is likely to be command line operations (e.g., an entry on how to run a local version of your server). Make sure snippets can be easily copy and pasted in the command line. This includes:

• Don’t include prompt symbols (leave the $ out of the $ cp /path/from /path/to snippet).
• If you expect some part of the command line to be replaced, try to position those arguments at the end. For example, replace mytool <file> --flag --another-flag with mytool --flag --another-flag <target>, so that it’s easier to copy, paste, edit and run. Another options is to use environment variables, e.g., mytool ${TARGET} --flag --another-flag so that readers could set that once and use the exact copied command.

Keep it as a one pager: Regardless of whether you keep your cheat sheet in Google docs, Confluence, Wiki or a Markdown file under version control, keep everything in one “document”. It’s easier to search in a huge page than navigate a complex structure.

Make it searchable: If you can’t (or won’t) use the one-pager approach, make sure entries can be easily found by adding relevant keywords. If you’re using a dedicated system (such as Atlassian’s Confluence), add as many relevant labels as you can for each page.

Make headers linkable: If possible, make sure you can link directly to specific entries inside the cheat sheet, so new folks can get what they want quickly and not feel lost in a huge block of text.

Similar Posts

• This TypeScript type haunted my dreams
• Thinking is developing mental models
• How I read nonfiction books
• How to pick a starter project that'll make someone quit
• Set up Obsidian URI handling on Linux
• Easy Recall Requires Multiple Contexts and Connections