The friction problem: Why we skip steps (even important ones)
How a simple link fixed our broken docs review process
The docs went live with errors. Users reported them within hours.
The review process was supposed to be simple: build the docs locally, check for broken links, formatting issues, rendering problems, then approve.
Except reviewers weren’t building the docs locally. They were skimming the markdown in the PR and hitting approve. “LGTM!” Without ever seeing the rendered output.
You can’t really blame them. Building docs locally means cloning the repo, installing dependencies, running a build command, waiting, then navigating to localhost. That’s five minutes of friction for a review that “should” take two. So they skip it and hope it renders fine.
This isn’t a discipline problem
It’s a friction problem.
We don’t skip important steps because we’re lazy. We skip them because the effort feels disproportionate to the task. A quick review shouldn’t require a local dev environment, but this one did. So the “quick review” quietly became “skim the markdown and approve.”
The fix was simple
We added automated PR previews. Every pull request now generates a deployed preview and drops the link in the PR comments.
“Click this link” replaced “build it locally.” One click versus five minutes of setup. Guess which one people actually do.
Review quality went up immediately. Not because we trained anyone, not because we wrote stricter guidelines, not because we added more process. We just removed the friction.
The pattern
This isn’t unique to doc reviews. Style guides get ignored when checking them by hand is a chore, so you put the linter in CI and suddenly everyone complies. Broken link checks never happen because clicking every link is tedious, so you automate them and they get caught before merge.
The step is important. Everyone agrees it’s important. We still skip it, and every time the reason is the same: too much friction for the value it delivers in the moment.
So instead of asking “why aren’t people following the process?”, ask “what’s making this process hard to follow?”
If you've run into something similar (a process that kept getting skipped until you found a way to reduce the friction) I'd love to hear about it in the comments.