# The docs route should fail in review, not in public > Why preview mode, isolated branches, pre-save linting, recurring docs audits, zero-lint merge gates, and teammate approval make documentation behave more like product infrastructure than website copy. - Canonical HTML: https://growth.iangoh.com/blog/the-docs-route-should-fail-in-review-not-in-public/ - Published: 2026-06-06 - Updated: 2026-06-06T09:04:00Z - Categories: documentation, SEO, brand trust - Niches: SaaS, AI products, developer tools, APIs, infrastructure software ## On this page - First, look at the page the way the reader will - Big rewrites should happen off the live route - Catch the small failures while the draft is still cheap - Then zoom out and treat the whole archive like a living surface - Critical docs should have merge rules, not only good intentions ## Start with these related tactics - [Preview mode before docs rewrite goes live](/growth-ideas/preview-mode-before-docs-rewrite-goes-live/): Review the docs in end-user preview mode before publishing a rewrite so navigation, scan flow, and trust cues get checked as a reader sees them. - [Branch-isolated docs rewrite before live nav change](/growth-ideas/branch-isolated-docs-rewrite-before-live-nav-change/): Draft major docs restructures on an isolated branch first so a navigation experiment or rewrite can be reviewed without touching the live archive. - [Docs linter runs before save, not after publish](/growth-ideas/docs-linter-runs-before-save-not-after-publish/): Run the docs linter before saving so broken links, placeholder text, and style drift get fixed while the change is still cheap. A lot of documentation teams still treat quality like a cleanup sprint. Publish first. Notice the damage later. Fix the broken links after support starts pasting apologies. That is backwards. By the time a docs mistake is public, it is already doing three jobs badly at once. It is confusing the reader, weakening the search route, and training the team to repeat the same answer in other channels. The better pattern is closer to product release discipline. The docs route should fail in review, not in public. ## First, look at the page the way the reader will [Preview mode before docs rewrite goes live](/growth-ideas/preview-mode-before-docs-rewrite-goes-live/) is the first habit I would steal. Editor chrome hides a lot. The left nav makes a page look more structured than it is, and the author already knows what the next step should be. Preview strips that comfort away. It belongs next to [custom docs 404 page with task-led redirects](/growth-ideas/custom-docs-404-page-with-task-led-redirects/). One checks the route before the mistake ships. The other cleans up the places where older routes still fail. ## Big rewrites should happen off the live route [Branch-isolated docs rewrite before live nav change](/growth-ideas/branch-isolated-docs-rewrite-before-live-nav-change/) is the part that gives the team room to think. Information architecture changes are dangerous because they feel reasonable in pieces. Live users feel the whole thing at once. This is the same instinct as [draft redirect review before GitBook cutover](/growth-ideas/draft-redirect-review-before-gitbook-cutover/). Structural changes deserve a safe place to compare the old route with the new one before the search traffic lands. ## Catch the small failures while the draft is still cheap [Docs linter runs before save, not after publish](/growth-ideas/docs-linter-runs-before-save-not-after-publish/) sounds procedural, but it fixes a real habit problem. Broken links, placeholder text, and tone drift are rarely deep strategy mistakes. They are usually timing mistakes. The team noticed too late. A pre-save check is boring in the right way. It makes quality debt less dramatic because it gets removed before it earns a public audience. ## Then zoom out and treat the whole archive like a living surface [Recurring docs audit for broken links and style drift](/growth-ideas/recurring-docs-audit-for-broken-links-and-style-drift/) is what keeps the old pages from quietly rotting while everyone is busy writing the new ones. Most docs debt arrives as drift, not disaster. That is why I still like [fail docs build on broken links before release](/growth-ideas/fail-docs-build-on-broken-links-before-release/) so much. The build gate protects the new change. The recurring audit protects the archive that is already out in the world. ## Critical docs should have merge rules, not only good intentions [Zero lint errors required before docs merge](/growth-ideas/zero-lint-errors-required-before-docs-merge/) and [teammate approval before docs merge on critical docs](/growth-ideas/teammate-approval-before-docs-merge-on-critical-docs/) are the quiet governance layer. These pages often answer pricing-adjacent questions, setup blockers, migration risks, and security objections. They deserve a real gate. If the docs sync with GitHub too, the branch names and review workflow stay easier to reason about. The point is not process theater. The point is making the public answer hard to change carelessly. This cluster is strongest for SaaS, AI products, developer tools, API companies, and infrastructure software where docs are part onboarding surface, part trust page, and part support system. If I were auditing a docs operation this week, I would ask six plain questions. Did we preview the page like a reader. Did the big rewrite stay off the live route. Did the draft hit the linter before save. Do recurring audits catch archive drift. Can known lint errors still slip through merge. Can one person rewrite the public answer alone. If you want help turning docs, trust surfaces, and AI-readable crawl assets into cleaner acquisition and conversion routes, the advisory CTA is here: [work with Ian Goh](https://iangoh.com/advisory). ## Related GrowthDex tactics - [Preview mode before docs rewrite goes live](/growth-ideas/preview-mode-before-docs-rewrite-goes-live/) - Documentation, SEO, Brand - [Branch-isolated docs rewrite before live nav change](/growth-ideas/branch-isolated-docs-rewrite-before-live-nav-change/) - Documentation, SEO, Operations - [Docs linter runs before save, not after publish](/growth-ideas/docs-linter-runs-before-save-not-after-publish/) - Documentation, SEO, Operations - [Recurring docs audit for broken links and style drift](/growth-ideas/recurring-docs-audit-for-broken-links-and-style-drift/) - Documentation, SEO, Analytics - [Zero lint errors required before docs merge](/growth-ideas/zero-lint-errors-required-before-docs-merge/) - Documentation, SEO, Operations - [Teammate approval before docs merge on critical docs](/growth-ideas/teammate-approval-before-docs-merge-on-critical-docs/) - Documentation, Brand, Support ## Essay chronology - [Newer essay: The JetBrains plugin page should finish the IDE trust check](/blog/the-jetbrains-plugin-page-should-finish-the-ide-trust-check/) - marketplaces, SEO, brand trust - [Older essay: The trust center should finish the security review before the inbox starts](/blog/the-trust-center-should-finish-the-security-review-before-the-inbox-starts/) - brand trust, security review, SEO ## Keep reading - [The docs route should let the developer verify before the call](/blog/the-docs-route-should-let-the-developer-verify-before-the-call/) - documentation, brand trust, SEO - [The Shopify app page should win the search result before the install](/blog/the-shopify-app-page-should-win-the-search-result-before-the-install/) - marketplaces, SEO, brand trust - [The AI visibility report should point to a page that can win](/blog/the-ai-visibility-report-should-point-to-a-page-that-can-win/) - AI visibility, SEO, brand trust ## Continue through the blog - [SaaS](/blog/#path-saas) - 3 essays in this path - [AI products](/blog/#path-ai-products) - 3 essays in this path - [developer tools](/blog/#path-developer-tools) - 3 essays in this path ## Sources - [ReadMe Docs: Navigate Your Docs](https://docs.readme.com/main/docs/navigating-your-hub-1) · [GrowthDex source hub](/sources/readme-docs-navigate-your-docs-docs-readme-com/) - [ReadMe Docs: Linter](https://docs.readme.com/main/docs/linter) · [GrowthDex source hub](/sources/readme-docs-linter-docs-readme-com/) - [ReadMe Docs: Docs Audit](https://docs.readme.com/main/docs/docs-audit) · [GrowthDex source hub](/sources/readme-docs-docs-audit-docs-readme-com/) - [ReadMe Docs: Reviews](https://docs.readme.com/main/docs/reviews) · [GrowthDex source hub](/sources/readme-docs-reviews-docs-readme-com/) - [ReadMe Docs: Sync with GitHub](https://docs.readme.com/main/docs/sync-with-github) · [GrowthDex source hub](/sources/readme-docs-sync-with-github-docs-readme-com/) ## Editing notes - Kept the essay on one claim: documentation quality should break in review before it leaks into the public route. - Used plain objects like nav changes, broken links, branch gates, public answers, and support apologies instead of abstract knowledge-language. - Cut broad AI-docs futurism and let the review mechanics carry the argument. - Ended with a six-question operator audit and direct advisory CTA instead of a soft summary. ## Advisory If you want help turning this into a growth system, Ian Goh offers advisory at https://iangoh.com/advisory.