DEV Community

David Boggs
David Boggs

Posted on Originally published at adaptiveips.com

Your SOP Is Probably Wrong. Build a Way to Notice.

Your SOP Is Probably Wrong. Build a Way to Notice.

An SOP can look finished long after it stops describing the work.

The screenshots still load. The numbered steps still make sense in isolation. But a permissions change means step 6 no longer works, so experienced staff use a workaround. New hires discover that workaround by asking someone. The document stays untouched because updating it feels like a separate project.

That is how process documentation becomes actively misleading. Nobody needs to decide to neglect it. Keeping the process running simply takes priority over describing it again.

The useful question is not "How do we get everyone to write more documentation?" It is "How do we make changes visible, cheap to document, and worth reviewing?"

Start with one frequently used procedure. Put it through the following maintenance loop before buying another documentation tool.

1. Capture the task while someone actually performs it

Writing an SOP from memory creates two jobs: reconstructing the work and explaining it. Reconstruction is where important details disappear.

An experienced operator remembers "grant access." They may not remember to document which request establishes authorization, which account they use, or how they verify the resulting permissions. Those details feel obvious to someone who performs the task every week.

Capture an actual execution instead.

Choose a representative case with a clear starting condition. For example, document granting an approved user access to an internal application. Start with the approved request visible, using sanitized data or a test environment where appropriate.

Ask the operator to narrate decisions as they work:

  • What makes this request eligible to proceed?
  • Why are they selecting this role?
  • What would make them stop and ask for clarification?
  • How will they know the change worked?

A recording preserves what happened on screen. Narration helps explain why it happened. Neither guarantees that the process is correct.

The operator may take an unnecessary detour or demonstrate a workaround that should be fixed. Treat the capture as source material for a draft, then have someone responsible for the process review it.

Screen recording also creates a data handling problem. Decide what must stay out of the capture before recording. Avoid exposing credentials, tokens, customer records, or unrelated browser tabs. If production capture is necessary, define who can access the recording and how long it should be retained.

The original recording may contain substantially more sensitive information than the finished SOP.

2. Turn the capture into a procedure someone else can execute

A transcript is not an SOP. Neither is a sequence of screenshots.

The finished procedure needs enough context for a qualified person to know when it applies and whether it succeeded. Use a compact header:

Procedure: Grant access to the internal reporting application
Owner: Application operations lead
Applies to: Standard employees with approved access requests
Does not cover: External users or elevated administrator access
Prerequisites: Approved request; authorized operator account
Revision: 4
Last validated: YYYY-MM-DD
Validated against: Application release/build, if available
Enter fullscreen mode Exit fullscreen mode

Then write steps around observable actions and results.

"Configure the appropriate permissions" leaves the decision undocumented. "Select the role named in the approved request, then verify that the saved assignment matches that role" gives the operator something to do and check.

Include a stop condition wherever continuing could create a bad outcome:

If the requested role is unavailable, stop and return the request
for clarification. Do not substitute a broader role.
Enter fullscreen mode Exit fullscreen mode

Screenshots should help someone locate a control or recognize a result. Do not make them the only place where a critical value or decision appears. Interfaces change, and images are harder to search than text.

Now give the draft to someone who understands the system but did not record the task. Have them execute it on a suitable test case without coaching from the author.

Every question they ask identifies a possible documentation gap. Record those questions instead of answering them verbally and leaving the draft unchanged.

This validation costs time. For a low-impact task, a short walkthrough may be enough. For a procedure that changes production access or can disrupt service, an independent execution is easier to justify.

3. Define what makes the SOP suspect

A review date is useful, but it is a weak detector of change.

A document can become wrong the day after its scheduled review. It can also remain accurate for a year. Age tells you when someone last checked it; it does not tell you whether the underlying process changed.

Give each procedure explicit staleness signals.

Signal Example Response
Relevant system change An application release changes role assignment Check affected steps before the next use
Execution mismatch An operator cannot find the documented control Flag the exact step and assess whether work can continue
Repeated clarification New hires keep asking which approval counts Add the missing decision rule
Unrecorded workaround Staff routinely skip a step to complete the task Investigate the workaround and revise the procedure or process
Ownership change The responsible team changes Assign a new owner and confirm scope
Elapsed review interval No validation has occurred within the chosen interval Revalidate based on the task's risk and frequency

These are operating rules you can implement with an issue tracker and a document repository. They do not require a specialized platform.

Make reporting a mismatch cheaper than fixing the whole document. A useful report can be four fields:

SOP and revision:
Step that differed:
What I observed:
Did I stop, continue, or use a workaround?
Enter fullscreen mode Exit fullscreen mode

Do not require the person doing urgent work to rewrite the SOP before they can report a problem. That requirement encourages silence.

The owner should then decide whether the mismatch is cosmetic, confusing, or unsafe. A renamed button may need a small correction. A missing authorization check may require suspending use until the procedure is fixed.

Mark unresolved problems where readers will see them before starting. A comment buried below the procedure is a poor warning system.

4. Separate learning evidence from execution evidence

"Can we prove someone followed the SOP?" sounds straightforward. It contains several different questions.

Opening a document shows access to it. Passing a quiz can provide evidence of understanding. Neither establishes that someone followed the procedure during a particular task.

Even a checked box usually establishes only that someone attested to completion.

For a specific execution, decide what evidence matters before designing the checklist. In the access example, that might mean linking the approved request to the resulting role assignment and recording who performed the change.

A minimal execution record could contain:

Work item:
SOP identifier and revision used:
Operator:
Execution date/time:
Required verification result:
Evidence reference:
Exception or deviation:
Enter fullscreen mode Exit fullscreen mode

The revision matters. If the SOP changes next week, a record that links only to the latest document leaves you guessing which instructions applied.

Choose evidence that supports the claim you need to make. A screenshot may show a result at one moment. An application audit event may establish that an account made a change. Neither necessarily explains whether the operator checked authorization first.

For higher-impact work, combine evidence from the work request and the target system where practical. Preserve the sequence when sequence matters.

Avoid collecting a recording of every execution by default. Recordings take time to review and can accumulate sensitive data. A narrowly scoped system event or verification result may provide better evidence with less exposure.

No practical record proves every thought or action. Be precise about what your evidence establishes and what it leaves uncertain.

5. Make updating part of the change itself

If an application change alters a documented workflow, documentation review belongs in that change's completion criteria.

Add a question to the existing change record:

Which SOPs are affected, and what validation supports leaving
them unchanged or publishing a new revision?
Enter fullscreen mode Exit fullscreen mode

"Documentation updated" is easy to check without thinking. Asking for affected procedures and validation creates a more useful review.

Keep the maintenance effort proportional to the change. A moved control may need one replacement screenshot and a revised instruction. A changed approval model needs a review of the decision logic, prerequisites, and execution evidence.

Recording the changed portion can help, but someone still needs to check that it fits the rest of the procedure. Otherwise, locally accurate edits can leave contradictory instructions elsewhere.

Assign ownership to a role with a named current assignee. "The team owns it" often means nobody has an explicit obligation to resolve reported defects.

Reserve time for that obligation. Faster drafting will not solve a queue of unreviewed changes.

Try the loop before evaluating software

Run a small pilot on one procedure that people already use.

Capture it during execution, validate the draft with another operator, and identify its staleness signals. On the next few executions, record which revision was used and whether anyone needed undocumented help.

Track the effort to produce a usable draft and the effort to correct it after a real change. Note where people abandon the prescribed workflow.

A growing library is not necessarily progress. Fewer unresolved mismatches and less dependence on verbal workarounds are more useful signs that the documentation is serving its purpose.

When evaluating tools, repeat the pilot with the same procedure. Test how easily you can correct a bad draft, replace an outdated step, and find the procedure using the words an operator would actually search for. Ask vendors to demonstrate any revision history or execution evidence capabilities you require.

Where our own product lands on this

Adaptive Cadence addresses the capture and drafting part of this problem. Screen-record a task and it drafts numbered steps with screenshots and the transcribed voiceover, turning operational knowledge into documented, searchable SOPs.

It also includes training quizzes, a manager coaching dashboard, and a department knowledge hub. You can deploy it on your own hardware or have us host it.

The practical fit is reducing the work between performing a task and producing documentation someone can review. Quizzes and coaching can support training, but should not be treated as proof that a particular execution followed an SOP.

You still need an owner, a way to detect changed behavior, and evidence appropriate to the task. Make those requirements explicit when evaluating Cadence.

Disclosure: I work at Adaptive IP Services, a Dallas based IT and security firm.

David J. Boggs
Founder and CEO, Adaptive IP Services

Adaptive Cadence

Top comments (0)