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 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 actual rendered output.
Can’t 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 pray it’ll render well.
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 it did. So the “quick review” 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 nobody follows because checking them is a chore → put linting in CI and suddenly everyone complies.
Broken link checks that never happen because clicking every link is tedious → automate it and they get caught before merge.
The step is important. We all agree it's important. We still skip it. Every time, the reason is the same: too much friction for the value it delivers in the moment.
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.