From db5ca367c1a8aa0d29c0237c451e5b9560900aab Mon Sep 17 00:00:00 2001 From: John Jeong Date: Tue, 2 Dec 2025 16:46:59 +0900 Subject: [PATCH] docs(article): add comprehensive guide to developer documentation tools --- .../developer-documentation-tools.mdx | 302 ++++++++++++++++++ 1 file changed, 302 insertions(+) create mode 100644 apps/web/content/articles/developer-documentation-tools.mdx diff --git a/apps/web/content/articles/developer-documentation-tools.mdx b/apps/web/content/articles/developer-documentation-tools.mdx new file mode 100644 index 000000000..81b7e4c2b --- /dev/null +++ b/apps/web/content/articles/developer-documentation-tools.mdx @@ -0,0 +1,302 @@ +--- +display_title: "Docs Edition: What to Use for Developer Documentation" +meta_title: "Developer Documentation Tools: What to Use in 2025" +meta_description: "A practical guide to choosing the right developer documentation stack in 2025. Compare file-based docs, Git-based CMS, headless CMS, hosted docs platforms, and fully custom documentation systems." +author: "John Jeong" +created: "2025-12-01" +coverImage: "/og/developer-docs-tools.png" +slug: "developer-documentation-tools" +--- + +Documentation is not the same thing as blogging. + +Docs are a product. + +People rely on them to unblock themselves, integrate with you, debug issues, and understand how your system actually works. + +So the tools you'd use for blog posts don't always work for docs. + +Docs need structure. + +Docs need navigation. + +Docs need versioning, API examples, sidebars, and searchable knowledge. + +But they also need to be maintainable by a real team — engineers, PMs, support, devrel — not just whoever has access to the CMS. + +This post is my honest breakdown of what tools you should consider in 2025 if you're building developer documentation from scratch. + +## There Are Really Only Five Kinds of Docs Systems + +No matter what marketing pages say, every modern docs system falls into one of these: + +1. **Pure File-Based (MD/MDX)** + → Docusaurus, Nextra, Mintlify Open Source, MkDocs, Astro + MDX + +2. **Git-Based CMS Layer on Top** + → Keystatic, TinaCMS, Decap + +3. **Headless CMS with Docs Frontend** + → Sanity, Payload, Contentful powering a docs UI + +4. **Hosted Docs Platforms** + → GitBook, Readme.com, Mintlify Cloud, Archbee, Notion (light docs) + +5. **Custom, In-Product Documentation** + → Your own framework + components (what many top devtools do) + +Each has a different cost model, maintenance profile, and failure mode. + +Let's break them down. + +## 1. Pure File-Based Docs (MDX) — The Default for Technical Teams + +This includes: + +- Docusaurus +- Nextra +- MkDocs / Material for MkDocs +- Astro + MDX +- TanStack Start + MDX + +This is the modern "docs-as-code" standard. + +### Pros + +- Lives in Git → versioned, diffable, PR-reviewable +- MD/MDX gives you unlimited flexibility +- Easy to automate (scripts, linting, link checking, TOC generation) +- Works perfectly with CI + preview deployments +- No vendor lock-in +- Very low maintenance overhead +- Free + +### Cons + +- Requires engineers to maintain structure +- Non-technical contributors may need training +- No built-in search unless you configure it +- No built-in analytics, roles, review workflows + +### When to Use It + +You're a technical team. + +You want control. + +You don't want to introduce complexity prematurely. + +You don't have 15 PMs writing docs every day. + +For 80% of startups, file-based MDX docs will be the right answer. + +This is what Vercel, Supabase, Clerk, Planetscale, PostHog, and most modern OSS projects use. + +## 2. Git-Based CMS Layer — Best Middle Ground + +Tools like: + +- Keystatic +- TinaCMS +- Decap CMS + +These tools give you a visual UI for editing docs while still using Markdown/MDX in Git. + +### Pros + +- Non-engineers can safely edit docs +- Still uses your repo as the source of truth +- No database migrations or content lakes +- Easy to adopt later (minimal migration) + +### Cons + +- Another admin app to host and maintain +- UI may not support advanced MDX patterns +- Contributors still need to understand the repo structure +- Slight complexity overhead + +### When to Use It + +Your PMs, DevRel, Support, or Marketing team needs to contribute regularly. + +But you want to maintain the "content lives in Git" principle. + +This is the "best of both worlds" middle layer. + +## 3. Headless CMS for Docs — Powerful but Often Overkill + +Using Sanity, Payload, or Contentful to power docs. + +### Pros + +- Strong content modeling +- Great for enterprises with localization, versioning, workflows +- Good structured content for advanced API docs +- Great for multi-surface (web, app, internal tools) + +### Cons + +- Massive configuration overhead +- Schema migrations become a real job +- Docs UI is never as natural as MDX +- Lock-in increases each quarter +- You are now maintaining a CMS backend forever + +### When to Use It + +You're big. + +You have multiple products, multiple locales, and multiple teams updating docs. + +Think Stripe-level documentation needs. + +If you're under 100 employees, this is almost always unnecessary. + +## 4. Hosted Docs Platforms — Fastest to Deploy, Most Lock-In + +Examples: + +- GitBook +- Mintlify Cloud +- Readme.com +- Archbee +- Notion (light docs) + +### Pros + +- Beautiful out of the box +- Built-in search, analytics, versioning +- Great WYSIWYG editors +- Good for non-technical writers +- Fastest path to "we have docs" + +### Cons + +- Hard to integrate tightly with your product or marketing site +- Proprietary content format (exports are messy) +- Limited MDX component support +- Outgrows you once you want custom layouts +- You become dependent on their roadmap + +### When to Use It + +You need docs fast, your team is mixed-technical, and you don't mind platform reliance. + +This works well for teams in a hurry or companies that don't have deep frontend capabilities. + +## 5. Custom In-Product Docs — The Future for Some Teams + +Many modern companies (Linear, Raycast, Warp, Replit) are increasingly embedding docs directly into their product or creating heavily customized documentation systems: + +- React/MDX component libraries +- Interactive playgrounds +- Copyable codeblocks +- Live components +- Search that ties into product data +- Custom navigation patterns +- AI-assisted docs generation / contextual help + +### Pros + +- Total control +- Can be integrated tightly with your app +- Interactive demos, live sandboxes, code runners +- Enables future AI-native experiences +- Perfect branding + +### Cons + +- Highest build & maintenance cost +- Requires strong frontend & infra engineering +- Docs become a product, not just content + +### When to Use It + +You're building a developer platform and your docs are part of your differentiation. + +This is the final evolution stage. + +## So… Which Should You Use in 2025? (Decision Guide) + +Here's the simplest way to not overthink it: + +**If your writers are engineers** → use file-based MDX docs. + +You'll ship faster than with any CMS. + +**If non-engineers need to edit** → add Keystatic/Tina. + +Do not jump to a headless CMS. + +**If you're large with multiple products + locales** → consider Sanity/Payload. + +But only when structure becomes real pain. + +**If you need something live tomorrow** → GitBook/Mintlify Cloud. + +Accept the lock-in for speed. + +**If your docs are part of your product** → build custom. + +This is where world-class developer tooling systems end up. + +## Things Most Teams Don't Realize About Docs + +### 1. Docs age faster than blogs + +They need pruning, refactoring, and maintenance. + +MDX makes this infinitely easier than any CMS. + +### 2. Versioning is non-negotiable + +If your API or SDK evolves, you need doc versioning. + +The simplest version? + +A folder per version in Git. + +A CMS makes this a nightmare. + +### 3. Search matters more than design + +Your docs UI can be plain — but your search must be excellent. + +Algolia DocSearch, Pagefind, or a custom hybrid works well. + +### 4. Docs need to survive your future rewrites + +Your framework will change. + +Your content shouldn't break with it. + +This is why MDX in Git is the gold standard. + +## What We're Betting On at Hyprnote + +We're building our docs on: + +- TanStack Start + MDX +- GitHub PR workflow +- Custom MDX components (callouts, tabs, code demos) +- Automatic TOC + search +- Keystatic layer as our team grows +- Future: interactive "live notebooks" tied to Hyprnote + +The principle is simple: + +**Docs are code.** + +And the best way to maintain code is with tools you already love. + +--- + +This is Part 5 of our publishing series. + +1. [Why We Write Our Blog in an IDE](/blog/using-ide-for-writing) +2. [Why Our CMS Is GitHub](/blog/why-our-cms-is-github) +3. [Choosing a CMS in 2025](/blog/choosing-a-cms) +4. [Don't Use a CMS Until You Absolutely Need One](/blog/dont-use-a-cms) +5. [Docs Edition: What to Use for Developer Documentation](/blog/developer-documentation-tools) (You are here) +6. [How We Built Hyprnote's Publishing Stack](/blog/hyprnote-publishing-stack)