My boss rejected an SOP I wrote because it wasn't detailed enough. I documented the action as: check the log for entries containing "Out of memory." He wants the procedure to explain everything, including how to connect over SSH, identify the correct log, and use commands such as tail and grep. I assumed that someone authorized to perform the task would already know basic shell commands or could look them up, but I'm starting to wonder whether an SOP should instead be written so that a new or less experienced team member can follow it without outside research. How do you decide the right level of detail, and where do you draw the line between an SOP, a runbook, and a general work instruction?
3 Answers
The audience determines the level of detail, but a good rule is that someone newly assigned to the role should be able to complete the task without guessing. Include the exact server or log location, the commands to run, expected output, warnings, and what to do if the result differs. You don’t necessarily need to teach Linux from scratch, but "check the log" is too vague if the procedure is meant to be repeatable and auditable.
Write it for the least experienced qualified person who may need it during an incident at 3 a.m. The point is not whether they can Google grep; it’s to make sure everyone follows the same safe process and doesn’t choose a different command or log file. Exact copy-and-paste commands and screenshots are especially useful when people are tired or under pressure.
There is a limit, though. Someone who doesn’t understand the system at all shouldn’t be making risky production changes just because they can follow a checklist. Include prerequisites, escalation points, and clear stop conditions.
A practical compromise is to separate the documentation into layers: a short overview or quick reference, a detailed step-by-step runbook, and reusable guides for tasks such as connecting to servers or searching logs. That gives experienced administrators a fast path while allowing a new operator to follow the full process. If the task is repetitive, consider automating the log check and documenting how to run and interpret the automation instead.
Also test the document with someone who didn’t write it. If they can follow it without asking what you meant, it’s probably detailed enough. Documentation often looks obvious to its author because the missing steps are already in their head.
For common basics, link to a separate SSH or shell guide rather than duplicating the explanation in every document. The main procedure can stay readable while still giving the operator everything needed.