What You're Actually Doing When You Write A Survival Guide
A survival guide is a document written for someone in a situation where they can't afford to figure things out in real time. That's it. The writing style is a direct consequence of the use case. If someone is reading this while their car is broken down in the snow, or their internet is down during a storm, or they just lost their keys and have no idea what room they're in, you don't have their attention for long. You have maybe thirty seconds before they panic and stop reading. I wrote a survival guide once for a internal team tool at my old company. We had a server outage that would knock out our entire production pipeline. I spent three weeks drafting it, making it comprehensive, citing every possible edge case, including diagnostic flowcharts and escalation paths. The first time it was actually used, one engineer opened it, scrolled past twelve inches of text, and said "where's the button I need to click." He had already restarted the service from memory by then. The guide was technically correct. It was also completely useless in the moment it was needed. This is the single biggest mistake people make. They write guides for calm people who are studying a problem. They need to write for stressed people who need an immediate answer.
How To Write A Survival Guide
Start with the action. Put the fix at the top of the document, not buried after two pages of background context. I reorganized that old guide so the single most critical step was on the first line. Everything else came after. Response time dropped from about five minutes to under forty seconds when someone hit that page during an incident. That's the difference a survival guide makes. Structure it in layers. The first layer is one sentence. This is what you do right now. The second layer is a numbered list of steps to do it. The third layer is the explanation of why those steps work. Most people will only ever read the first two layers. But the third layer exists for the person who reads it later and needs to understand the root cause so they can fix something similar next time. Don't skip the third layer. It's what separates a survival guide from a quick fix that leaves everyone confused. The order doesn't have to be linear either. Here's how I actually draft mine now. I write the steps first, because that's what matters. Then I go back and add the context and definitions. Then I strip everything I can from the top. Usually the final version is a fraction of what I started with.
Use specific language, not general advice. "Check the connection" means nothing to someone who doesn't know which connection, where it is, or what it should look like when it's working. "Look for the green LED on port B. If it's flashing amber, unplug the cable and plug it back in." That's useful. That's what a survival guide needs. I learned this the hard way with a home server setup I documented for my family. We had a power outage last winter and my dad called me at 2 AM. He couldn't reach the guide because I'd written "ensure the UPS is functioning" instead of telling him which switch to flip and which light to check. He reset the breaker, waited ten seconds, flipped the main switch on the UPS. Power came back. The guide could have told him to do that in four seconds instead of having to wait for a phone call. I rewrote it after that. Never again. Include failure modes. This is something almost nobody does. Every survival guide should have a section that says what to do when the steps don't work. Your first fix failed. Now what? You need a decision tree, not another paragraph of hope.
Get the Full Details
Here's a common pitfall with survival guides: they assume the reader has the same environment you do. You tested your fix on a clean setup. The person using your guide is running something completely different and your steps won't apply. Add a prerequisites section at the very top. List what the reader needs to have or know before they attempt anything. This saves them from following three steps only to realize they're missing the one thing they need and wasting twenty minutes. Write for the worst version of your reader. Not the distracted version. The worst version. The one who doesn't know the terminology, who might be reading on a phone with a dead battery, who might have been awake for sixteen hours. Assume they're at their absolute worst. If the guide works for that person, it works for everyone. I use a test where I hand the draft to someone who has zero context about the problem. I watch them try to follow it without explaining anything. Whatever they get stuck on, whatever they ask about, that's what needs to be added to the guide. It takes about ten minutes and it catches more issues than any amount of self-review ever will. I've done this on half a dozen guides now. The feedback is always brutally obvious in hindsight.
Keep it under one page if possible. A survival guide longer than a page is usually a troubleshooting document, not a survival guide. These are different things. A troubleshooting doc is for when you have time. A survival guide is for when you don't. If your guide is scrolling on a phone screen for more than a few seconds, it's too long. Compress it. Remove the stuff that's nice to know. Keep only the stuff that's necessary to survive. The other limitation nobody talks about: survival guides become obsolete fast. Systems change. Updates happen. Someone adds a new feature that breaks your old instructions. I've seen guides that were perfect six months ago and are now completely wrong because an update changed the interface. The workaround is to add a version stamp and a date at the top. If the date is more than six months old, treat the guide as suspect until you verify it. Nobody will do this for you. You have to build it into the process. There's also the question of format. Some people prefer a markdown file. Some prefer a web page. Some prefer a physical printout. For personal use, a markdown file in a known location on your machine works fine. For team use or public use, a hosted page is better because it can be updated without redistributing anything. Both approaches have tradeoffs. Markdown is portable and version-controllable. A web page is searchable and shareable but requires hosting and a maintenance habit. Pick one and stick with it.
The core principle is simple enough that it's easy to ignore in practice. You're not writing for a student. You're writing for someone who needs to act immediately and can't think clearly. Everything you add that doesn't help them act faster is just noise. Strip it out. Write the one thing they need to know first. Then the next thing. Then stop. If you want something concrete to start with, take a problem you've solved recently. Write down exactly what you did, in order. Read it once and cut half of it. Read it again and cut more. Then give it to someone who doesn't know the problem and watch them use it. That's the entire process. Not much more to it than that.
