My manager rejected an SOP I wrote because it didn't include enough detail. I wrote a step like, "Check the log for entries containing 'Out of memory,'" assuming that someone authorized to perform the procedure would know how to connect to the server and use basic commands such as tail and grep. My manager wants the document to explain everything step by step, including how to connect and run the commands. I understand the argument for making procedures accessible, but I'm concerned that documenting extremely basic skills makes the SOP unnecessarily long. How do you decide the right level of detail, and where do you draw the line between an SOP and a more detailed work instruction or runbook?
4 Answers
Your example is probably too vague. “Check the log” leaves unanswered questions: which machine, which file, which account, what exact command, what time range, and what should the operator do if they find a match? A command such as `grep -i "out of memory" /path/to/application.log` gives the operator something concrete and makes the process repeatable. The document should also explain the purpose and expected result, not just list keystrokes.
The right detail level depends on the audience. A procedure for experienced Tier 3 administrators can focus on what needs to happen and link to reusable runbooks for the mechanics. A document for help desk staff, new hires, or emergency coverage should be much more explicit. It also helps to separate the layers: a short overview or quick reference, followed by detailed work instructions and troubleshooting notes.
Modular documentation prevents duplication. Put common tasks such as connecting to a server or searching logs in their own maintained guides, then reference them from the main SOP.
Regardless of what the document is called, your manager has given you the acceptance criteria. Revise it to match the requested standard, then suggest a better documentation structure afterward. For recurring manual checks, consider automating or scripting the log search once the process is well understood. The resulting SOP can explain how to run the check and interpret the output instead of making someone manually repeat a long sequence.
Write for the least experienced qualified person who may need to perform the task, especially during an outage or at 3 a.m. The purpose isn’t to test whether someone can Google a command; it’s to make sure the procedure is performed consistently and safely. Include the exact server, log path, command, expected output, warnings, and what to do next. Screenshots can help for GUI work, while copy-and-pasteable commands are useful for command-line procedures.
That doesn’t mean the document has to teach all of Linux. You can link to a separate SSH or shell guide for general skills while still giving the exact command and target needed for this procedure.
At the same time, excessive detail can make a procedure harder to follow. Keep the main path clear, put screenshots and background information in supporting sections, and call out points where the operator must stop or escalate.