Separating Docs from Marketing: A Developer Platform Pattern

One of the earliest infrastructure decisions for any developer platform is whether documentation lives inside the marketing website or separately. The answer seems obvious — it’s all content, put it in one site — until you start building and realize the two have fundamentally different concerns.

We separated them from day one: the marketing site lives at www.smplkit.com, documentation lives at docs.smplkit.com. Different repos, different deployment pipelines, different design priorities. Here’s why.

Different Cadences

The marketing site changes when the business changes: new pricing, new product launch, updated messaging. That’s a handful of deploys per month, and each one usually touches several pages at once.

Documentation changes when the code changes. A new API endpoint ships, the docs update. A parameter gets renamed, the docs update. An SDK version bumps, the docs update. That can mean multiple deploys per week, and each one is typically a surgical change to one page.

Coupling these two cadences means every marketing copy tweak goes through the same pipeline as API documentation updates. You either slow down docs deployments with marketing review processes, or you risk breaking marketing pages with documentation changes.

Different Audiences

Marketing content is for people deciding whether to use your product. It needs to convince, differentiate, and communicate value. The design priorities are brand consistency, visual impact, and narrative flow.

Documentation is for people who have already decided to use your product. It needs to inform, guide, and reference. The design priorities are readability, searchability, and accuracy.

Trying to serve both audiences with the same information architecture leads to compromise in both directions. Marketing pages get cluttered with technical detail. Documentation pages get burdened with sales messaging. Neither audience gets what they need.

Different Frameworks

Our marketing site is a Next.js static site — good for rich landing pages, product showcases, and marketing content. Our documentation site is VitePress — purpose-built for developer documentation with Markdown authoring, built-in search, and clean navigation.

If the two lived in the same repo, we’d have to pick one framework that serves both purposes, or maintain a monorepo with two build systems. Neither option is appealing.

Separate repos mean each site uses the framework best suited to its purpose. VitePress is excellent at documentation and terrible at marketing pages. Next.js is excellent at marketing pages and adequate at documentation. Using each where it excels is better than forcing one to do both.

The Pattern in the Wild

This isn’t a novel architecture. Look at how mature developer platforms organize their web properties:

Stripe has stripe.com (marketing) and docs.stripe.com (documentation). Twilio has twilio.com and twilio.com/docs. Major observability platforms follow the same pattern with separate marketing and documentation subdomains. The specifics vary (subdomain vs. path), but the principle is universal: marketing and documentation are operationally separate.

We chose the subdomain approach — docs.smplkit.com — because it gives us complete independence. Different DNS, different hosting, different repo, different everything. A path-based approach (smplkit.com/docs) would require the two to share a deployment pipeline, which reintroduces the coupling we’re trying to avoid.

Hosting Symmetry

Both sites deploy on AWS Amplify from their respective GitHub repos. Push to main and the site builds and deploys automatically. Same workflow, same hosting platform, completely independent pipelines.

This symmetry is nice because it means the deployment model is identical even though everything else is different. One fewer thing to remember.

The Repo Structure That Makes It Work

Each repo is self-contained. The marketing site repo has its own package.json, its own build configuration, its own preview deployments. The docs repo has its own. Neither needs to know the other exists.

When a new product ships, the marketing site gets a new product page (marketing repo) and the docs site gets SDK guides and API reference additions (docs repo). The two changes happen in parallel, in different PRs, deployed independently. A typo fix on the docs site doesn’t trigger a marketing site build. A pricing page update doesn’t rebuild the documentation.

The shared element between them is the top-level navigation. Both sites include links to each other — the docs site links back to the marketing site, and the marketing site links to docs. This is just HTML links, not a shared component library or a monorepo dependency.

When You Might Choose Differently

If your documentation is small — a single getting-started page and an API reference — putting it on the marketing site is fine. The complexity of managing two sites isn’t worth it until you have enough documentation that it needs its own navigation, its own search, and its own update cadence.

For smplkit, that threshold was reached early. A multi-product platform with SDK documentation, API references, guides, and tutorials needs a dedicated documentation site from the start. Retrofitting one later means migrating content, fixing links, and dealing with SEO redirects.

Start separated. It’s easier to merge two sites than to split one.

smplkit documentation lives at docs.smplkit.com. The marketing site you’re reading now is at www.smplkit.com.