Should we use a hosted docs platform like Mintlify or build our own?

For most B2B SaaS teams, hosted (Mintlify, ReadMe, Stoplight) is the right starting point. They give you the standard left-nav, middle-content, right-code layout out of the box, opinionated information architecture and minimal dev investment. Open-source generators like Docusaurus, Mkdocs Material or Starlight give more control with more work. Custom Astro or Next.js builds make sense when docs are a key differentiator. The tool matters less than editorial discipline. A well-maintained Mkdocs site beats a neglected custom build every time.

Why does docs site search matter so much?

Search is the single most-used feature on a docs site after the first visit. Engineers Google specific error messages and parameter names, and once they're inside the docs they search constantly. If your search returns three irrelevant results for "webhook" they stop trusting the entire platform within minutes. Hold docs search to a real standard. Algolia DocSearch is the default and it's good. Self-hosted Meilisearch works too. The WordPress search box on a Gutenberg-built docs page does not, and engineers will write off the whole product.

Should we treat developer docs as a marketing or an engineering responsibility?

Both, with shared accountability. Marketing rarely owns the technical accuracy and engineering rarely prioritises the design and editorial polish. The docs sites that get used have a product manager or technical writer holding the editorial standard, an engineering team owning the API reference accuracy and a design partner keeping the experience aligned with the marketing brand. The split-ownership pattern fails when docs become a maintenance task between sprints. Treat them as a product, not an afterthought.

Designing developer documentation sites that get used

Developer documentation sits in an awkward spot for most SaaS companies. Marketing doesn’t own it, product doesn’t quite own it and engineering treats it as a maintenance task between sprints. The result is a site that’s technically accurate but visually neglected, hard to navigate and nearly impossible to find specific information in. Engineers work around it by guessing at endpoints or asking on Slack. Sales feels the impact when prospects say “we couldn’t get the integration working in our trial”.

We’ve designed and rebuilt developer docs for B2B SaaS clients selling to engineering teams. The patterns that separate docs that get used from docs that get ignored are surprisingly consistent. Most aren’t about technical accuracy. They’re about design.

What developer docs are actually for

Three audiences hit a docs site in any given week and they want different things. Evaluating engineers during a trial want to know whether the API can do what they need before they invest more time. Implementing engineers who’ve signed want copy-pasteable examples and clear authentication flow. Maintaining engineers debugging an existing integration want to find one specific endpoint or error code fast.

A docs site optimised for one audience often fails the others. The default failure is to design entirely for implementing engineers and leave evaluators to flounder.

The first 30 seconds

Evaluating engineers make a fast decision. If the docs site doesn’t communicate, within 30 seconds, what the API does, how authentication works and where the quickstart lives, they bounce.

Three things we put above the fold on every docs landing page:

A one-sentence statement of what the API actually does, in the language an engineer evaluating you would use. Not “the most powerful API for X” but “REST API for sending transactional email at scale”.
A “Quickstart in 5 minutes” link. Direct, not buried under “Getting started” with twelve sub-pages.
A code sample showing one realistic call. Not a “Hello world” placeholder.

That last one matters more than people realise. A docs landing page with no code on it tells the engineer this isn’t going to be a comfortable experience.

Search has to actually work

Search is the single most-used feature on a docs site after the first visit. If it returns three irrelevant results for “webhook”, engineers stop trusting it within minutes. Hold docs search to a real standard: indexes everything (page bodies, code samples, parameter names, error codes), returns results within 200 ms, highlights matches in context, handles fuzzy matching and includes a keyboard shortcut (cmd-K or /).

Algolia DocSearch is the default and it’s good. Self-hosted alternatives like Meilisearch work too. What doesn’t work is the WordPress search box on a Gutenberg-built docs site. Engineers will write off the whole platform.

Information architecture that respects the user

The structural pattern that consistently works:

Section	Purpose	Audience
Quickstart	Working code in 5 minutes	Evaluators
Concepts	What the system actually does	Evaluators and new implementers
API reference	Every endpoint, parameter, response	All audiences
Guides	How to do specific tasks	Implementers
SDKs	Language-specific libraries	Implementers
Changelog	What changed and when	Maintainers

The most common error we see is collapsing this into a flat menu of every endpoint, which forces evaluating engineers to reverse-engineer the product from the API alphabet. The conceptual layer matters.

Code samples as a first-class concern

Code samples are the most-read content on a docs site and the most under-invested. Show code in multiple languages with a tab switcher (cURL, Python, Node, Go covers most B2B SaaS audiences). Make every sample copy-pasteable with a visible button. Use realistic data, not placeholders. acme@example.com with realistic field names reads like the API was designed by people who use APIs. customer@example.com reads as fake.

For SDK pages, an installation snippet, an authentication snippet and one realistic end-to-end example beat fifteen edge-case examples no engineer reads.

The API reference layout

The standard pattern (left navigation, middle content, right code panel) became standard because it works. Stripe popularised it, Twilio refined it and it’s now the expected layout for any docs site that wants to look credible. Departing from it is rarely a good idea.

What goes on each side:

Left: hierarchical navigation, collapsible by section.
Middle: human-readable explanation of what an endpoint does, parameter table, example response.
Right: live code sample in the language the user picked, sticky as they scroll.

For tools like Mintlify, ReadMe, Docusaurus, Mkdocs Material and GitBook, this layout is built in. For custom docs on Astro, Next.js or a headless CMS, it’s the layout to copy.

What to put in every endpoint page

A consistent template per endpoint reduces cognitive load: endpoint URL and method displayed prominently, one-sentence description, authentication requirement, parameter table (name, type, required, description), copy-pasteable example request, full realistic example response and error codes with handling guidance.

The error codes section is the one most often skipped. It’s the one engineers hit when something breaks at 11pm on a Friday. Investing in it pays back disproportionately in support load.

Performance and accessibility

A docs site has to be fast. Engineers run it on a laptop with twelve other tabs open. Lighthouse scores below 90 are a problem. We covered the principles in our page speed checklist for tech sites and the broader Core Web Vitals 2026 angle. Accessibility matters too. Keyboard navigation, semantic HTML and proper colour contrast aren’t negotiable. See WCAG accessibility for tech companies.

SEO for docs sites

Developer docs are often a SaaS company’s strongest SEO asset and the team running them rarely realises it. Engineers Google specific error messages, parameter names and integration questions. A docs site that ranks well for “stripe webhook signature verification” or “twilio rate limit error” pulls in qualified traffic that converts.

Practical points:

Each endpoint page should have a clear title tag including the method and resource name.
Meta descriptions should describe what the endpoint does in one sentence.
Schema markup matters. We covered this in schema markup for SaaS websites and the AI-search angle in structured data for AI search.
Internal linking from concept pages to reference pages and back. Our piece on internal linking for tech sites covers the broader rules.
Cross-linking from marketing site to docs and back, with consistent navigation.

This last point is more important than people realise. We see SaaS companies with a beautiful marketing site and a docs site that feels like it belongs to a different company. The visitor moves between them mid-evaluation and the disconnect signals a less polished operation.

Versioning, deprecation and changelogs

Three operational decisions affect long-term docs health.

If the API has versions, the docs need them. A version selector in the nav with content branching cleanly between versions. Don’t try to fold version differences into a single page with “v2 only” callouts.

When an endpoint is deprecated, the docs page for it needs a visible banner saying when it’ll be removed and what to use instead. Not a footnote. A banner at the top in a colour that hasn’t been used elsewhere.

A genuine, dated changelog beats “we made improvements”. Specific changes: “Added metadata field to POST /charges. Deprecated legacy_id, removal scheduled for 2026-09-01.” Engineers subscribe to changelog RSS feeds. A docs site without one is one they have to check manually, which means they don’t.

Tooling choice

Docs platform options for B2B SaaS in 2026 sit in rough tiers. Mintlify, ReadMe and Stoplight are hosted, opinionated and fast to set up; good for companies who want a polished docs site without dev investment. Docusaurus, Mkdocs Material and Starlight are open-source static-site generators with more control and more dev work. Astro or Next.js custom builds give maximum control, worth it where docs are a key differentiator. Bolt-on to WordPress or Webflow is rarely a good idea unless the docs are very shallow. We covered the wider platform comparison in WordPress vs Webflow for B2B tech.

The tool matters less than the editorial discipline. A well-maintained Mkdocs site beats a neglected custom build every time.

The takeaway

Developer docs are a product, not a marketing afterthought. The companies that treat them that way win evaluating engineers in trials and reduce support load through implementation. The ones that don’t pay for it in deals that quietly slip and integrations that never finish.

If any of this lands, start a conversation. You can also see how we approach product-led design on our web design service page and the content side on our content marketing service page.