content: When to Move from Help Center to Docs-as-Code

src/content/blog/technical/help-center-to-docs-as-code.mdx

@@ -0,0 +1,105 @@
+---
+title: 'Help Center vs Docs-as-Code: When to Switch'
+subtitle: Published April 2026
+description: >-
+  A practical guide to choosing between a help center and docs-as-code, with specific signals for when to migrate and when to stay.
+date: '2026-04-01T00:00:00.000Z'
+author: Frances
+section: Technical
+hidden: false
+---
+import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro';
+import BlogRequestDemo from '@components/site/BlogRequestDemo.astro';
+
+At some point, most teams that start with help center docs ask the same question: should we move from our help center to docs-as-code? This article tries to give you a decision framework.
+
+## The Core Tradeoff
+
+Help centers (Zendesk, Confluence, Freshdesk, Notion) are built for non-technical authors. WYSIWYG editors, inline commenting, article voting, ticketing integration. Anyone can publish without touching a command line.
+
+Docs-as-code (Docusaurus, MkDocs, Starlight, Mintlify) inverts this. Documentation lives in Git alongside the codebase. Changes go through pull requests. Deployment happens via CI/CD pipeline. Engineers can contribute without leaving their environment.
+
+Both approaches create friction for someone. Help centers create friction for developers. Docs-as-code creates friction for support staff, legal, and anyone who doesn't work in Git. The decision is about which direction of friction costs you more. That depends on who writes and who consumes your documentation.
+
+| | Help center | Docs-as-code |
+|---|---|---|
+| **Best for** | Customer support, FAQs, stable products | Developer-facing docs, APIs, fast-moving products |
+| **Authoring** | WYSIWYG, no technical knowledge needed | Markdown in Git, requires developer familiarity |
+| **Developer contribution** | High friction: context switch out of IDE | Low friction: same workflow as code changes |
+| **Non-technical contributors** | Low friction | High friction: Git barrier excludes most |
+| **Version control** | Article-level restore only | Full Git branching, concurrent version support |
+| **CI/CD integration** | Not supported | Native |
+| **Cost** | Per-seat licensing bundled with support suite | Free (open source) or per-seat (managed platforms) |
+| **Setup overhead** | Hours | Weeks to months |
+
+## When to Move
+
+### Developers are your primary SMEs and they're refusing to contribute
+
+This is the most reliable signal. If engineers are the primary source of technical knowledge and they won't touch the help center, documentation will decay regardless of what processes you put in place. Context-switching from an IDE to a browser-based editor is real friction, and developers will choose the path of least resistance.
+
+Docs-as-code removes that barrier. A pull request that updates documentation alongside code uses the same workflow as one that fixes a bug. 56% of developer documentation teams already follow a docs-as-code approach, with another 22% doing so partially, per [Tom Johnson's survey](https://idratherbewriting.com/learnapidoc/docapis_trends.html) of 400+ developer documentation professionals.
+
+### You have an API or SDK and developers are your primary audience
+
+[84% of developers](https://www.cherryleaf.com/2024/07/survey-shows-documentation-is-the-no-1-way-that-developers-learn-about-your-api/) use technical documentation as their primary learning resource (Stack Overflow 2024). When they evaluate your API, the docs signal product quality. A help center can publish technical reference content, but it can't branch documentation alongside software releases or participate in a CI/CD pipeline. Those gaps matter more as developer tooling evolves.
+
+### You need concurrent documentation for multiple software versions
+
+Help centers have article-level restore, not branching. Maintaining v1 and v2 API docs simultaneously in a help center has no clean answer. Git does. If your team is shipping multiple concurrent versions and manually juggling content between articles, this alone justifies the move.
+
+### Engineers are shipping frequently and documentation needs to keep pace
+
+When a product changes fast, the people with the most current knowledge are the engineers writing the code. If the tooling makes it hard for them to update documentation, it won't get updated. Docs-as-code lowers that barrier directly. A documentation change can travel in the same pull request as the code change that made it necessary.
+
+The caveat here is what actually changes from the user's perspective. A product can have high internal velocity while exposing a stable interface. Think of how the ChatGPT interface has always been a text box. The underlying model and infrastructure changed constantly, but what users interacted with stayed the same. If most of the engineering work is below the surface and the user-facing product is relatively stable, documentation needs are still driven by customer support, and a help center handles that well. The relevant question is not how fast engineering ships, but how often what users see and interact with changes.
+
+### Your documentation release process is a manual bottleneck
+
+[Tom Johnson's team](https://idratherbewriting.com/learnapidoc/pubapis_switching_to_docs_as_code.html) migrated a large documentation site from a Java CMS to Jekyll and Git. A 40-page release that previously required hours of manual copy-paste now deploys in 10 minutes via a single `git push`. If the publishing step is where releases get stuck, the pipeline change pays for itself quickly.
+
+<BlogNewsletterCTA />
+
+If you're starting your docs from scratch, we'll always recommend docs-as-code. If you're already on help center, and moving will incur real cost, here are some reasons not to move.
+
+## When Not to Move
+
+### You have a large non-technical contributor base
+
+If compliance, legal, or support staff regularly author or review documentation, the git barrier makes it difficult for them. That said, this is a weaker reason to stay put than it used to be. AI coding tools are making it easier for non-technical contributors to interact with Git-based workflows using natural language, and that shift is accelerating.
+
+### Your product is mature and the user-facing interface is stable
+
+If what users see and interact with changes slowly, most of your documentation work is supporting customers: answering recurring questions and helping users through a known set of issues. That is exactly what help centers are built for.
+
+Product velocity alone is not the right signal. A mature B2B SaaS with a stable product is a fine candidate for a help center even if the engineering team is active. What matters is whether the changes engineering ships affect what users need to know. If most of the work is behind the curtain, the documentation surface stays small and a help center handles it without friction.
+
+### Your audience is non-technical end users
+
+Docs-as-code is optimized for developer-facing products. If your product is a no-code SaaS tool with a support-heavy customer base, the help center's ticketing integration, article voting, and familiar search UI are genuine advantages. Moving to a static site built for developers solves a problem you don't have.
+
+## The Middle Path
+
+Managed docs-as-code platforms like Mintlify and GitBook layer visual editing on top of Git backends. Non-technical contributors get a WYSIWYG interface; engineers get Git-native workflows.
+
+[HubSpot moved](https://developers.hubspot.com/blog/optimizing-developer-docs-in-the-age-of-ai-our-mintlify-migration-story) from a custom-built internal documentation platform to Mintlify. Their description of the trigger was direct: the documentation team was functioning as an "accidental platform team," maintaining infrastructure instead of doing developer experience work. AI tooling made the problem visible: assistants were pulling from v1 and v3 API docs simultaneously and returning conflicting answers.
+
+The tradeoff with managed platforms is per-seat licensing and vendor dependency. Pure static site generators are free and fully customizable but require engineering to set up and maintain.
+
+## What Migration Actually Costs
+
+Plan for the migration to take longer than expected.
+
+First, audit the content. Not everything in a help center needs to move. Support FAQs and account management articles may belong in the help center permanently. Technical reference and API docs are the migration candidates.
+
+Conversion takes weeks for a large site. You'll run both systems simultaneously while converting. Users can't wait for the migration to finish. URL structures change, which means redirect maps need to be built before you cut over. Translation workflows need to be solved before you start, not after; most localization vendors can't handle mixed Markdown and HTML.
+
+## What Migration Doesn't Solve
+
+Moving to docs-as-code makes it easier for engineers to contribute. It doesn't guarantee they will. Documentation decay comes from a structural timing gap: engineering ships continuously, documentation reviews happen in batches. Changing the tooling removes one barrier but doesn't automatically close the gap between when a product changes and when the docs reflect that change.
+
+Regardless of which system you're in, you need a way to detect when [documentation has drifted](/blog/technical/documentation-drift-detection-problem) from the product it describes. That's a monitoring problem that exists on both sides of the migration. Teams with accurate documentation treat it as [a continuous monitoring task](/blog/technical/how-teams-keep-docs-up-to-date-with-promptless), not a periodic side project.
+
+If you want to put your docs on autopilot, see a demo here.
+
+<BlogRequestDemo />

src/pages/blog/index.astro

@@ -25,6 +25,7 @@ const USE_CASES_SLUGS = new Set([
   'technical/agent-context-engineering',
   'technical/support-agent-deflection',
   'technical/agent-memory-provider',
+  'technical/help-center-to-docs-as-code',
 ]);
 
 const FEATURED_SLUGS = new Set([