From 393d24f5c9c752cbcda20b732701b274e39e3979 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 6 Nov 2025 15:42:21 +0000 Subject: [PATCH 1/6] feat(docs): add Stainless vs Fern comparison pages as hidden resources - Add comprehensive comparison document (stainless-comparison-full.mdx) - Add concise summary comparison (stainless-comparison-summary.mdx) - Mark both pages as hidden in docs.yml navigation - Pages accessible only via direct link for sales engineering use Co-Authored-By: Chris McDonnell --- fern/products/docs/docs.yml | 11 + .../resources/stainless-comparison-full.mdx | 406 ++++++++++++++++++ .../stainless-comparison-summary.mdx | 135 ++++++ 3 files changed, 552 insertions(+) create mode 100644 fern/products/docs/pages/resources/stainless-comparison-full.mdx create mode 100644 fern/products/docs/pages/resources/stainless-comparison-summary.mdx diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index cea1de77..e23ba5ae 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -287,4 +287,15 @@ navigation: path: ./pages/developer-tools/vale.mdx - page: View Markdown path: ./pages/developer-tools/view-markdown.mdx + - section: Resources + collapsed: true + contents: + - page: Stainless vs Fern comparison (full) + path: ./pages/resources/stainless-comparison-full.mdx + slug: resources/stainless-comparison-full + hidden: true + - page: Stainless vs Fern comparison (summary) + path: ./pages/resources/stainless-comparison-summary.mdx + slug: resources/stainless-comparison-summary + hidden: true \ No newline at end of file diff --git a/fern/products/docs/pages/resources/stainless-comparison-full.mdx b/fern/products/docs/pages/resources/stainless-comparison-full.mdx new file mode 100644 index 00000000..df4332a8 --- /dev/null +++ b/fern/products/docs/pages/resources/stainless-comparison-full.mdx @@ -0,0 +1,406 @@ +--- +title: Stainless Docs vs Fern Docs - Detailed comparison +description: Comprehensive enterprise feature comparison between Stainless Docs and Fern Docs platforms +--- + +# Stainless Docs vs Fern Docs: Enterprise Feature Comparison + +## Executive Summary + +Fern Docs is a production-ready, enterprise-grade documentation platform with comprehensive features for large-scale API documentation, while Stainless Docs Platform remains in early access with significant feature gaps for enterprise deployments. + +**Key Enterprise Advantages of Fern:** + +1. **Production Maturity**: Fern is production-ready and battle-tested, while Stainless explicitly warns of "breaking changes before 1.0" in their early access phase. + +2. **Visual Editor & Governance**: Fern provides a WYSIWYG visual editor with GitHub App integration for non-technical authors, enabling broader team collaboration. Stainless only supports Git-based workflows requiring technical expertise. + +3. **RBAC & Multi-Instance Deployment**: Fern offers audience-based content filtering (RBAC) to show/hide products, versions, and pages across different instances (internal vs. public). Stainless has no documented support for this critical enterprise requirement. + +4. **API Versioning & Multi-Product Sites**: Fern provides first-class API versioning with availability states and multi-product documentation in a single site. Stainless lacks documented versioning capabilities. + +5. **Interactive API Explorer**: Fern includes a built-in API Explorer for testing endpoints directly in documentation with environment/auth support, auto-populated credentials, and WebSocket testing. Stainless has no documented API playground. + +6. **Enterprise Authentication**: Fern integrates with WorkOS for enterprise SSO (SAML/OIDC). Stainless authentication is limited to API keys for their service, not end-user SSO. + +7. **Full-Stack Self-Hosting**: Fern offers a complete Docker container with database, object storage, search, and UI for regulated environments. Stainless only supports static file hosting. + +8. **Advanced AI Capabilities**: Fern provides Ask Fern chatbot, guidance documents, Documents API, Slack bot, MCP server auto-generation, and analytics/insights. Stainless offers basic RAG search without operational controls. + +9. **Multi-Spec Support**: Fern supports OpenAPI, AsyncAPI, gRPC, OpenRPC, and Fern spec. Stainless only supports OpenAPI + Stainless config. + +10. **Enterprise Infrastructure**: Fern runs on AWS VPC with PostgreSQL, Redis, S3, and integrates with Algolia, PostHog, TurboPuffer. Stainless emphasizes Cloudflare static hosting. + +--- + +## Detailed Feature Comparison + +### 1. Platform Maturity and Stability + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Production Status** | ✅ Production-ready, stable | ⚠️ Early access with breaking changes expected | +| **API Stability** | ✅ Stable CLI/docs pipeline | ❌ "Expect breaking changes to APIs before 1.0" | +| **Enterprise Deployments** | ✅ Widely deployed (ElevenLabs, Webflow, Hume AI, etc.) | ⚠️ Limited production usage | +| **Documentation Completeness** | ✅ Comprehensive (11,947 lines) | ⚠️ Basic documentation (limited pages) | + +**Citations:** +- Stainless: https://www.stainless.com/docs/docs-platform/ - "The Stainless Docs Platform is currently in early access. Expect breaking changes to APIs before 1.0." +- Fern: https://buildwithfern.com/learn/docs/getting-started/quickstart + +**Gap Analysis:** Stainless is not ready for enterprise production deployments where API stability and backward compatibility are critical. Fern's production-ready status makes it suitable for mission-critical documentation. + +--- + +### 2. Content Authoring and Governance + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Visual WYSIWYG Editor** | ✅ Fern Editor with Tiptap | ❌ Not documented | +| **GitHub App Integration** | ✅ Automatic PR creation | ❌ Not documented | +| **Non-Technical Author Support** | ✅ Visual editor for writers | ❌ Requires Git/code knowledge | +| **Dashboard Management** | ✅ Org members, repos, domains | ⚠️ Basic dashboard for API keys | +| **Content Format** | ✅ MDX with React components | ✅ MDX/Markdoc | +| **Markdown Partials** | ✅ Snippets system | ✅ Markdown partials | + +**Citations:** +- Fern Editor: https://buildwithfern.com/learn/docs/writing-content/fern-editor +- Fern Dashboard: https://dashboard.buildwithfern.com +- Stainless: https://www.stainless.com/docs/docs-platform/ - No visual editor mentioned + +**Gap Analysis:** Stainless requires all authors to use Git workflows and code editors, limiting collaboration to technical team members. Fern's visual editor democratizes documentation authoring, enabling technical writers, product managers, and support teams to contribute without Git expertise. + +--- + +### 3. API Reference and Interactive Testing + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Interactive API Explorer** | ✅ Full playground with auth | ❌ Not documented | +| **Auto-Populated Credentials** | ✅ When authenticated | ❌ Not documented | +| **WebSocket Testing** | ✅ Real-time testing | ❌ Not documented | +| **Audio Streaming Support** | ✅ Stream audio in explorer | ❌ Not documented | +| **Environment Switching** | ✅ Production/Sandbox toggle | ❌ Not documented | +| **Language-Specific SDK Docs** | ✅ Multi-language support | ✅ Language-specific pages | +| **Spec Format Support** | ✅ OpenAPI, AsyncAPI, gRPC, OpenRPC, Fern | ⚠️ OpenAPI + Stainless config only | + +**Citations:** +- Fern API Explorer: https://buildwithfern.com/learn/docs/api-references/api-explorer/overview +- Fern Multi-Spec: https://buildwithfern.com/learn/docs/api-references/generate-api-ref +- Stainless: https://www.stainless.com/docs/docs-platform/api-and-sdk-reference/overview/ - No API playground mentioned + +**Gap Analysis:** Stainless lacks an interactive API testing environment, forcing developers to use external tools like Postman or curl. Fern's integrated API Explorer reduces friction and enables developers to test endpoints without leaving the documentation, with automatic credential injection for authenticated users. + +--- + +### 4. RBAC, Versioning, and Multi-Product Support + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Audience Filtering (RBAC)** | ✅ Content gating by audience | ❌ Not documented | +| **Multi-Instance Deployment** | ✅ Internal vs. public sites | ❌ Not documented | +| **API Versioning** | ✅ Version management with availability states | ❌ Not documented | +| **Multi-Product Documentation** | ✅ Multiple products in one site | ❌ Not documented | +| **Version-Specific Pages** | ✅ Per-version content | ❌ Not documented | +| **Namespace Organization** | ✅ Organized by product/version | ⚠️ Basic tabs (Guides/Reference) | + +**Citations:** +- Fern Audiences: https://buildwithfern.com/learn/docs/configuration/what-is-docs-yml (audiences section) +- Fern Versions: https://buildwithfern.com/learn/docs/configuration/what-is-docs-yml (versions section) +- Stainless Navigation: https://www.stainless.com/docs/docs-platform/navigation/ - Only basic tabs, no versioning + +**Gap Analysis:** Stainless cannot support common enterprise scenarios like: +- Showing different documentation to internal vs. external users +- Maintaining multiple API versions with deprecation notices +- Hosting documentation for multiple products in a unified site +- Controlling content visibility based on customer tier or role + +Fern's RBAC and versioning capabilities are essential for enterprises with complex API portfolios and diverse user bases. + +--- + +### 5. AI-Powered Search and Assistance + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **AI Chatbot** | ✅ Ask Fern with Claude/Cohere | ✅ RAG-based Q&A | +| **Guidance Documents** | ✅ Override AI responses | ❌ Not documented | +| **Documents API** | ✅ Custom knowledge sources | ❌ Not documented | +| **Slack Bot Integration** | ✅ `/fern` command | ❌ Not documented | +| **MCP Server** | ✅ Auto-generated for AI clients | ❌ Not documented | +| **Analytics & Insights** | ✅ Content gap identification | ❌ Not documented | +| **Vector Search** | ✅ TurboPuffer integration | ⚠️ Metadata-driven indexing | +| **Faceted Search** | ✅ By language, product, version | ✅ By language, resource type | +| **LLM-Friendly Format** | ✅ /llms.txt and /llms-full.txt | ✅ .md extension on URLs | + +**Citations:** +- Ask Fern: https://buildwithfern.com/learn/ask-fern/getting-started/what-is-ask-fern +- Fern MCP Server: https://buildwithfern.com/learn/docs/ai-features/mcp-server +- Fern llms.txt: https://buildwithfern.com/learn/docs/seo/llms-txt +- Stainless Search: https://www.stainless.com/docs/docs-platform/ - Basic RAG, no operational controls + +**Gap Analysis:** While both platforms offer AI-powered search, Fern provides enterprise-grade operational controls: +- **Guidance documents** let you prescribe exact answers for sensitive topics +- **Documents API** enables adding internal knowledge bases and support articles +- **Analytics** identify documentation gaps based on unanswered questions +- **MCP server** enables AI coding assistants to access your docs programmatically + +Stainless offers basic RAG search without the operational controls needed for enterprise deployments where answer accuracy and compliance are critical. + +--- + +### 6. Authentication and Security + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Enterprise SSO** | ✅ WorkOS (SAML/OIDC/SCIM) | ❌ Not documented | +| **Role-Based Access** | ✅ Audience-based content gating | ❌ Not documented | +| **Authenticated Pages** | ✅ Login-protected documentation | ❌ Not documented | +| **API Key Management** | ✅ Auto-populate in explorer | ⚠️ API keys for Stainless service only | +| **JWT Token Support** | ✅ Automatic extraction | ❌ Not documented | + +**Citations:** +- Fern WorkOS: https://buildwithfern.com/learn/docs/getting-started/how-fern-docs-work (WorkOS integration) +- Stainless Auth: https://www.stainless.com/docs/docs-platform/advanced/stainless-authentication/ - Only API keys for their service + +**Gap Analysis:** Stainless's "authentication" refers to API keys for accessing their documentation generation service, not end-user authentication for viewing documentation. Fern's WorkOS integration provides enterprise SSO, enabling: +- SAML/OIDC authentication for employees and customers +- Role-based content visibility +- Compliance with security policies requiring authenticated documentation access +- Integration with existing identity providers (Okta, Azure AD, etc.) + +--- + +### 7. Hosting and Deployment + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Cloud Hosting** | ✅ Vercel with AWS VPC backend | ✅ Cloudflare (default) | +| **Self-Hosted Full Stack** | ✅ Docker with DB, storage, search | ❌ Static files only | +| **Database Included** | ✅ PostgreSQL in self-hosted | ❌ Not applicable | +| **Object Storage** | ✅ S3/MinIO in self-hosted | ❌ Not applicable | +| **Search Engine** | ✅ MeiliSearch in self-hosted | ❌ Not applicable | +| **Custom Domains** | ✅ Full support | ✅ Full support | +| **CDN Integration** | ✅ Cloudflare + Vercel Edge | ✅ Cloudflare | + +**Citations:** +- Fern Self-Hosted: https://buildwithfern.com/learn/docs/self-hosted/overview +- Fern Architecture: https://buildwithfern.com/learn/docs/getting-started/how-fern-docs-work +- Stainless Hosting: https://www.stainless.com/docs/docs-platform/hosting-and-deploys/ - Static hosting only + +**Gap Analysis:** Stainless can only deploy static HTML/CSS/JS files, requiring customers to provide their own infrastructure for: +- Search indexing and querying +- User authentication and session management +- Analytics and usage tracking +- Dynamic content generation +- API proxy for CORS + +Fern's self-hosted Docker container includes all necessary services (PostgreSQL, MinIO, MeiliSearch, FDR, Next.js UI), making it suitable for regulated industries (healthcare, finance, government) that require on-premises deployment with full data sovereignty. + +--- + +### 8. Redirects, SEO, and Large-Site Operations + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Advanced Redirects** | ✅ 299+ rules with pattern matching | ❌ Not documented | +| **Redirect Parameters** | ✅ `:slug` and `:splat` support | ❌ Not documented | +| **Permanent Redirects** | ✅ 301/302 support | ❌ Not documented | +| **SEO Optimization** | ✅ Meta tags, JSON-LD, RSS | ✅ Basic meta tags | +| **Sitemap Generation** | ✅ Automatic | ✅ Automatic (assumed) | +| **robots.txt** | ✅ Automatic | ✅ Automatic (assumed) | +| **Social Sharing** | ✅ OG images, Twitter cards | ⚠️ Basic support | + +**Citations:** +- Fern Redirects: https://buildwithfern.com/learn/docs/configuration/what-is-docs-yml (redirects section) +- Fern SEO: https://buildwithfern.com/learn/docs/seo/llms-txt +- Stainless: No redirect documentation found + +**Gap Analysis:** Large documentation sites require redirect management when restructuring content, deprecating pages, or migrating from other platforms. Fern's redirect system supports: +- Pattern matching with wildcards +- Parameter preservation across redirects +- Permanent vs. temporary redirects +- Hundreds of rules managed in `docs.yml` + +Stainless lacks documented redirect capabilities, making it unsuitable for migrations or large-scale content reorganization. + +--- + +### 9. Analytics and Observability + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Analytics Integration** | ✅ PostHog, Google Analytics | ❌ Not documented | +| **Search Analytics** | ✅ Query tracking and insights | ❌ Not documented | +| **AI Chat Analytics** | ✅ Question/answer tracking | ❌ Not documented | +| **Content Gap Identification** | ✅ Unanswered questions report | ❌ Not documented | +| **Custom Event Tracking** | ✅ Via PostHog | ❌ Not documented | +| **Performance Monitoring** | ✅ Vercel Analytics | ⚠️ Cloudflare Analytics | + +**Citations:** +- Fern Analytics: https://buildwithfern.com/learn/docs/getting-started/how-fern-docs-work (PostHog integration) +- Fern Insights: https://buildwithfern.com/learn/ask-fern/ (insights section) +- Stainless: No analytics documentation found + +**Gap Analysis:** Fern provides comprehensive analytics to understand documentation usage: +- Which pages are most/least visited +- What users are searching for +- Which questions Ask Fern cannot answer (content gaps) +- User journey through documentation +- API Explorer usage patterns + +This data-driven approach enables continuous documentation improvement. Stainless lacks documented analytics capabilities. + +--- + +### 10. Extensibility and Integrations + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Component Library** | ✅ 30+ pre-built components | ⚠️ Standard library | +| **Custom React Components** | ✅ Full support | ✅ Via Astro | +| **Custom CSS/JS** | ✅ Full support | ✅ Full support | +| **Third-Party Integrations** | ✅ Algolia, PostHog, WorkOS, etc. | ⚠️ Astro ecosystem | +| **MCP Server** | ✅ Auto-generated | ❌ Not documented | +| **Webhook Support** | ✅ For AI chat events | ❌ Not documented | +| **API for Programmatic Updates** | ✅ FDR API | ❌ Not documented | + +**Citations:** +- Fern Components: https://buildwithfern.com/learn/docs/writing-content/components/overview +- Fern Custom CSS: https://buildwithfern.com/learn/docs/customization/custom-css-js +- Stainless Customization: https://www.stainless.com/docs/docs-platform/customization/styles-and-fonts/ + +**Gap Analysis:** Both platforms support customization, but Fern provides deeper integration capabilities: +- **MCP server** enables AI coding assistants (Cursor, Copilot) to access documentation +- **Webhooks** enable custom workflows triggered by AI chat events +- **FDR API** enables programmatic documentation updates +- **30+ components** provide rich documentation experiences out-of-the-box + +Stainless emphasizes Astro's ecosystem but lacks the enterprise integrations Fern provides. + +--- + +## Technology Stack Comparison + +### Fern Docs +- **Frontend**: Next.js (React) with SSR/SSG +- **Backend**: Node.js/Express (FDR) on AWS VPC +- **Database**: PostgreSQL +- **Cache**: Redis, Vercel KV (Upstash) +- **Storage**: S3 (AWS/MinIO) +- **Search**: Algolia, MeiliSearch (self-hosted) +- **Vector DB**: TurboPuffer +- **AI**: Bedrock, Claude, Cohere +- **Auth**: WorkOS +- **CDN**: Cloudflare + Vercel Edge +- **Analytics**: PostHog +- **Deployment**: Vercel, Docker (self-hosted) + +### Stainless Docs +- **Frontend**: Astro (static site generator) +- **Backend**: Stainless API service +- **Database**: Not applicable (static) +- **Cache**: Cloudflare CDN +- **Storage**: Not applicable (static) +- **Search**: Metadata-driven indexing +- **Vector DB**: Not documented +- **AI**: RAG with LLM (provider not specified) +- **Auth**: API keys (for Stainless service) +- **CDN**: Cloudflare (default) +- **Analytics**: Not documented +- **Deployment**: Cloudflare, any static host + +--- + +## Use Case Recommendations + +### Choose Fern Docs When: +1. **Enterprise Requirements**: You need RBAC, SSO, versioning, or multi-product documentation +2. **Regulated Industries**: You require self-hosted deployment with full data sovereignty +3. **Interactive Testing**: Developers need to test APIs directly in documentation +4. **Non-Technical Authors**: Technical writers and product managers need to contribute without Git +5. **Advanced AI**: You need operational controls over AI answers (guidance docs, custom sources) +6. **Large-Scale Sites**: You're managing complex documentation with hundreds of pages and redirects +7. **Analytics-Driven**: You want data on documentation usage and content gaps +8. **Multi-Spec Support**: You use AsyncAPI, gRPC, or OpenRPC in addition to OpenAPI +9. **Production Stability**: You need a stable, battle-tested platform with backward compatibility +10. **Comprehensive Support**: You want white-glove migration and ongoing support + +### Choose Stainless Docs When: +1. **Early Adopter**: You're comfortable with early access software and breaking changes +2. **Simple Documentation**: You have straightforward documentation needs without versioning or RBAC +3. **Astro Expertise**: Your team prefers Astro and wants deep customization control +4. **Static Hosting**: You only need static file hosting without backend services +5. **SDK-Centric**: Your primary focus is SDK documentation generated from Stainless SDKs +6. **Technical Team**: All documentation authors are comfortable with Git workflows +7. **Basic Search**: Metadata-driven search without operational AI controls is sufficient +8. **Cost-Sensitive**: You want to minimize hosting costs with static files +9. **Cloudflare Preference**: You're committed to Cloudflare's ecosystem +10. **Patience for Maturity**: You can wait for the platform to reach 1.0 stability + +--- + +## Migration Considerations + +### Migrating from Stainless to Fern +- **Effort**: Medium - Content can be migrated from MDX/Markdoc to Fern MDX +- **OpenAPI Compatibility**: High - Fern supports OpenAPI specs directly +- **Custom Components**: Requires rewriting Astro components as React components +- **Redirects**: Fern's redirect system can maintain URL compatibility +- **Timeline**: Fern offers white-glove migration service for Enterprise customers + +### Migrating from Other Platforms to Fern +- **Readme.com**: High compatibility, similar component library +- **GitBook**: Medium effort, content structure differs +- **Docusaurus**: Medium effort, React components compatible +- **Mintlify**: High compatibility, similar MDX approach +- **Swagger UI**: Low effort for API reference, need to add guides + +--- + +## Pricing Considerations + +### Fern Docs +- **Starter**: Free tier available +- **Pro**: Usage-based pricing +- **Enterprise**: Custom pricing with white-glove migration, dedicated support, SLA +- **Self-Hosted**: Available for Enterprise customers + +### Stainless Docs +- **Pricing**: Not publicly documented (early access) +- **Requires**: Stainless SDK generation service + +--- + +## Conclusion + +Fern Docs is the clear choice for enterprise organizations requiring production-ready documentation with advanced features like RBAC, versioning, interactive API testing, visual editing, enterprise SSO, and full-stack self-hosting. The platform's maturity, comprehensive feature set, and robust infrastructure make it suitable for mission-critical documentation at scale. + +Stainless Docs Platform shows promise with its Astro-based architecture and SDK-native approach, but remains in early access with significant feature gaps for enterprise deployments. Organizations should wait for Stainless to reach production maturity before considering it for critical documentation needs. + +For enterprises evaluating documentation platforms today, Fern Docs provides the stability, features, and support required for successful API documentation programs. + +--- + +## Additional Resources + +### Fern Docs +- **Documentation**: https://buildwithfern.com/learn/docs/ +- **Quickstart**: https://buildwithfern.com/learn/docs/getting-started/quickstart +- **API Explorer**: https://buildwithfern.com/learn/docs/api-references/api-explorer/overview +- **Self-Hosted**: https://buildwithfern.com/learn/docs/self-hosted/overview +- **Ask Fern**: https://buildwithfern.com/learn/ask-fern/ +- **GitHub**: https://github.com/fern-api/fern +- **Contact**: https://buildwithfern.com/contact + +### Stainless Docs +- **Documentation**: https://www.stainless.com/docs/docs-platform/ +- **Quickstart**: https://www.stainless.com/docs/docs-platform/quickstart/ +- **Interest Form**: https://www.stainless.com/products/docs +- **Feedback**: feedback@stainless.com + +--- + +*Document Version: 1.0* +*Last Updated: November 6, 2025* +*Prepared for: Fern Sales Engineering* diff --git a/fern/products/docs/pages/resources/stainless-comparison-summary.mdx b/fern/products/docs/pages/resources/stainless-comparison-summary.mdx new file mode 100644 index 00000000..68da310b --- /dev/null +++ b/fern/products/docs/pages/resources/stainless-comparison-summary.mdx @@ -0,0 +1,135 @@ +--- +title: Stainless Docs vs Fern Docs - Quick comparison +description: Concise comparison highlighting enterprise feature gaps between Stainless Docs and Fern Docs +--- + +# Stainless Docs vs Fern Docs: Quick Comparison + +## TL;DR + +**Fern Docs** is production-ready and enterprise-grade with comprehensive features. **Stainless Docs** is in early access with significant feature gaps for enterprise deployments. + +--- + +## Top 10 Enterprise Gaps Where Stainless Falls Short + +### 1. Platform Maturity ⚠️ +- **Stainless**: Early access, "expect breaking changes before 1.0" +- **Fern**: Production-ready, stable, widely deployed +- **Impact**: Stainless not suitable for mission-critical documentation + +### 2. Visual Editor & Non-Technical Authors ❌ +- **Stainless**: Git-only workflow, requires technical expertise +- **Fern**: WYSIWYG Fern Editor + GitHub App for writers/PMs +- **Impact**: Stainless limits collaboration to engineers only + +### 3. RBAC & Audience Filtering ❌ +- **Stainless**: No documented support +- **Fern**: Content gating by audience (internal vs. public, by tier) +- **Impact**: Cannot show different docs to different user groups + +### 4. API Versioning ❌ +- **Stainless**: No documented versioning system +- **Fern**: First-class versioning with availability states +- **Impact**: Cannot maintain multiple API versions simultaneously + +### 5. Interactive API Explorer ❌ +- **Stainless**: No documented playground +- **Fern**: Full API testing with auto-populated credentials, WebSocket support +- **Impact**: Developers must use external tools (Postman, curl) + +### 6. Enterprise SSO ❌ +- **Stainless**: API keys for their service only +- **Fern**: WorkOS integration (SAML/OIDC/SCIM) +- **Impact**: Cannot require authentication for viewing docs + +### 7. Full-Stack Self-Hosting ❌ +- **Stainless**: Static files only +- **Fern**: Complete Docker container (DB, storage, search, UI) +- **Impact**: Not suitable for regulated industries requiring on-prem + +### 8. AI Operational Controls ❌ +- **Stainless**: Basic RAG search +- **Fern**: Guidance docs, Documents API, Slack bot, MCP server, analytics +- **Impact**: Cannot control AI answers or add custom knowledge sources + +### 9. Multi-Spec Support ⚠️ +- **Stainless**: OpenAPI + Stainless config only +- **Fern**: OpenAPI, AsyncAPI, gRPC, OpenRPC, Fern spec +- **Impact**: Limited to REST APIs, no event-driven or RPC support + +### 10. Advanced Redirects & SEO ❌ +- **Stainless**: No documented redirect system +- **Fern**: 299+ redirect rules with pattern matching +- **Impact**: Difficult to migrate or restructure large sites + +--- + +## Feature Matrix + +| Category | Fern | Stainless | +|----------|------|-----------| +| **Maturity** | ✅ Production | ⚠️ Early Access | +| **Visual Editor** | ✅ Yes | ❌ No | +| **API Explorer** | ✅ Yes | ❌ No | +| **RBAC/Audiences** | ✅ Yes | ❌ No | +| **Versioning** | ✅ Yes | ❌ No | +| **Enterprise SSO** | ✅ WorkOS | ❌ No | +| **Self-Hosted** | ✅ Full Stack | ⚠️ Static Only | +| **AI Controls** | ✅ Advanced | ⚠️ Basic | +| **Multi-Spec** | ✅ 5 formats | ⚠️ OpenAPI only | +| **Redirects** | ✅ 299+ rules | ❌ No | +| **Analytics** | ✅ PostHog | ❌ No | +| **Multi-Product** | ✅ Yes | ❌ No | + +--- + +## When to Choose Each + +### Choose Fern When: +- ✅ Enterprise requirements (RBAC, SSO, versioning) +- ✅ Regulated industries (self-hosted required) +- ✅ Non-technical authors need to contribute +- ✅ Interactive API testing is important +- ✅ Production stability is critical +- ✅ Advanced AI with operational controls +- ✅ Large-scale documentation (100+ pages) +- ✅ Multi-product or multi-version APIs + +### Choose Stainless When: +- ⚠️ Comfortable with early access software +- ⚠️ Simple docs without versioning/RBAC +- ⚠️ All authors are technical (Git comfortable) +- ⚠️ Static hosting is sufficient +- ⚠️ Astro expertise and preference +- ⚠️ Can wait for 1.0 stability + +--- + +## Key Links + +### Fern Resources +- **Overview**: https://buildwithfern.com/learn/docs/ +- **Quickstart**: https://buildwithfern.com/learn/docs/getting-started/quickstart +- **Fern Editor**: https://buildwithfern.com/learn/docs/writing-content/fern-editor +- **API Explorer**: https://buildwithfern.com/learn/docs/api-references/api-explorer/overview +- **Self-Hosted**: https://buildwithfern.com/learn/docs/self-hosted/overview +- **Ask Fern AI**: https://buildwithfern.com/learn/ask-fern/ +- **Contact**: https://buildwithfern.com/contact + +### Stainless Resources +- **Overview**: https://www.stainless.com/docs/docs-platform/ +- **Early Access Warning**: https://www.stainless.com/docs/docs-platform/ (top of page) +- **Interest Form**: https://www.stainless.com/products/docs + +--- + +## Bottom Line + +**Fern Docs** is the enterprise-ready choice with production stability, comprehensive features, and robust infrastructure. **Stainless Docs** shows promise but remains in early access with critical feature gaps for enterprise deployments. + +For organizations evaluating documentation platforms today, Fern provides the maturity, features, and support required for mission-critical API documentation. + +--- + +*For detailed analysis, see the [full comparison document](/learn/docs/resources/stainless-comparison-full)* From 7fbc16232fc19740b248952c0c0d221483d8736f Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 6 Nov 2025 15:48:00 +0000 Subject: [PATCH 2/6] fix(docs): address Vale linting issues in comparison summary - Use sentence-style capitalization for all headings - Replace 'Visual Editor' with 'Fern Editor' - Replace 'Cannot' with 'can't' for contractions Co-Authored-By: Chris McDonnell --- .../stainless-comparison-summary.mdx | 48 +++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/fern/products/docs/pages/resources/stainless-comparison-summary.mdx b/fern/products/docs/pages/resources/stainless-comparison-summary.mdx index 68da310b..850793d0 100644 --- a/fern/products/docs/pages/resources/stainless-comparison-summary.mdx +++ b/fern/products/docs/pages/resources/stainless-comparison-summary.mdx @@ -3,7 +3,7 @@ title: Stainless Docs vs Fern Docs - Quick comparison description: Concise comparison highlighting enterprise feature gaps between Stainless Docs and Fern Docs --- -# Stainless Docs vs Fern Docs: Quick Comparison +# Stainless Docs vs Fern Docs: Quick comparison ## TL;DR @@ -11,29 +11,29 @@ description: Concise comparison highlighting enterprise feature gaps between Sta --- -## Top 10 Enterprise Gaps Where Stainless Falls Short +## Top 10 enterprise gaps where Stainless falls short -### 1. Platform Maturity ⚠️ +### 1. Platform maturity ⚠️ - **Stainless**: Early access, "expect breaking changes before 1.0" - **Fern**: Production-ready, stable, widely deployed - **Impact**: Stainless not suitable for mission-critical documentation -### 2. Visual Editor & Non-Technical Authors ❌ +### 2. Fern Editor & non-technical authors ❌ - **Stainless**: Git-only workflow, requires technical expertise - **Fern**: WYSIWYG Fern Editor + GitHub App for writers/PMs - **Impact**: Stainless limits collaboration to engineers only -### 3. RBAC & Audience Filtering ❌ +### 3. RBAC & audience filtering ❌ - **Stainless**: No documented support - **Fern**: Content gating by audience (internal vs. public, by tier) -- **Impact**: Cannot show different docs to different user groups +- **Impact**: Can't show different docs to different user groups -### 4. API Versioning ❌ +### 4. API versioning ❌ - **Stainless**: No documented versioning system - **Fern**: First-class versioning with availability states -- **Impact**: Cannot maintain multiple API versions simultaneously +- **Impact**: Can't maintain multiple API versions simultaneously -### 5. Interactive API Explorer ❌ +### 5. Interactive API explorer ❌ - **Stainless**: No documented playground - **Fern**: Full API testing with auto-populated credentials, WebSocket support - **Impact**: Developers must use external tools (Postman, curl) @@ -41,36 +41,36 @@ description: Concise comparison highlighting enterprise feature gaps between Sta ### 6. Enterprise SSO ❌ - **Stainless**: API keys for their service only - **Fern**: WorkOS integration (SAML/OIDC/SCIM) -- **Impact**: Cannot require authentication for viewing docs +- **Impact**: Can't require authentication for viewing docs -### 7. Full-Stack Self-Hosting ❌ +### 7. Full-stack self-hosting ❌ - **Stainless**: Static files only - **Fern**: Complete Docker container (DB, storage, search, UI) - **Impact**: Not suitable for regulated industries requiring on-prem -### 8. AI Operational Controls ❌ +### 8. AI operational controls ❌ - **Stainless**: Basic RAG search - **Fern**: Guidance docs, Documents API, Slack bot, MCP server, analytics -- **Impact**: Cannot control AI answers or add custom knowledge sources +- **Impact**: Can't control AI answers or add custom knowledge sources -### 9. Multi-Spec Support ⚠️ +### 9. Multi-spec support ⚠️ - **Stainless**: OpenAPI + Stainless config only - **Fern**: OpenAPI, AsyncAPI, gRPC, OpenRPC, Fern spec - **Impact**: Limited to REST APIs, no event-driven or RPC support -### 10. Advanced Redirects & SEO ❌ +### 10. Advanced redirects & SEO ❌ - **Stainless**: No documented redirect system - **Fern**: 299+ redirect rules with pattern matching - **Impact**: Difficult to migrate or restructure large sites --- -## Feature Matrix +## Feature matrix | Category | Fern | Stainless | |----------|------|-----------| | **Maturity** | ✅ Production | ⚠️ Early Access | -| **Visual Editor** | ✅ Yes | ❌ No | +| **Fern Editor** | ✅ Yes | ❌ No | | **API Explorer** | ✅ Yes | ❌ No | | **RBAC/Audiences** | ✅ Yes | ❌ No | | **Versioning** | ✅ Yes | ❌ No | @@ -84,9 +84,9 @@ description: Concise comparison highlighting enterprise feature gaps between Sta --- -## When to Choose Each +## When to choose each -### Choose Fern When: +### Choose Fern when: - ✅ Enterprise requirements (RBAC, SSO, versioning) - ✅ Regulated industries (self-hosted required) - ✅ Non-technical authors need to contribute @@ -96,7 +96,7 @@ description: Concise comparison highlighting enterprise feature gaps between Sta - ✅ Large-scale documentation (100+ pages) - ✅ Multi-product or multi-version APIs -### Choose Stainless When: +### Choose Stainless when: - ⚠️ Comfortable with early access software - ⚠️ Simple docs without versioning/RBAC - ⚠️ All authors are technical (Git comfortable) @@ -106,9 +106,9 @@ description: Concise comparison highlighting enterprise feature gaps between Sta --- -## Key Links +## Key links -### Fern Resources +### Fern resources - **Overview**: https://buildwithfern.com/learn/docs/ - **Quickstart**: https://buildwithfern.com/learn/docs/getting-started/quickstart - **Fern Editor**: https://buildwithfern.com/learn/docs/writing-content/fern-editor @@ -117,14 +117,14 @@ description: Concise comparison highlighting enterprise feature gaps between Sta - **Ask Fern AI**: https://buildwithfern.com/learn/ask-fern/ - **Contact**: https://buildwithfern.com/contact -### Stainless Resources +### Stainless resources - **Overview**: https://www.stainless.com/docs/docs-platform/ - **Early Access Warning**: https://www.stainless.com/docs/docs-platform/ (top of page) - **Interest Form**: https://www.stainless.com/products/docs --- -## Bottom Line +## Bottom line **Fern Docs** is the enterprise-ready choice with production stability, comprehensive features, and robust infrastructure. **Stainless Docs** shows promise but remains in early access with critical feature gaps for enterprise deployments. From cce45eb4d42057205934694852ba91bbac1e498d Mon Sep 17 00:00:00 2001 From: Fern Support <126544928+fern-support@users.noreply.github.com> Date: Thu, 6 Nov 2025 10:51:12 -0500 Subject: [PATCH 3/6] Update slugs for stainless comparison pages --- fern/products/docs/docs.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index e23ba5ae..0059c4a7 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -292,10 +292,10 @@ navigation: contents: - page: Stainless vs Fern comparison (full) path: ./pages/resources/stainless-comparison-full.mdx - slug: resources/stainless-comparison-full + slug: stainless-comparison-full hidden: true - page: Stainless vs Fern comparison (summary) path: ./pages/resources/stainless-comparison-summary.mdx - slug: resources/stainless-comparison-summary + slug: stainless-comparison-summary hidden: true - \ No newline at end of file + From 0701a8e510e479045242b22ce481d8c1f5c6163e Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 6 Nov 2025 15:59:28 +0000 Subject: [PATCH 4/6] feat(docs): enhance comparison documents with Fern components - Add CardGroup with icons for top 10 enterprise gaps in summary - Convert detailed feature sections to Accordions in full document - Add Info, Success, Warning, and Launch callouts throughout - Enhance key links section with Cards for better organization - Improve visual hierarchy and readability with collapsible sections - Make documents more digestible and scannable for sales engineering use Co-Authored-By: Chris McDonnell --- .../resources/stainless-comparison-full.mdx | 74 ++++--- .../stainless-comparison-summary.mdx | 204 +++++++++++------- 2 files changed, 167 insertions(+), 111 deletions(-) diff --git a/fern/products/docs/pages/resources/stainless-comparison-full.mdx b/fern/products/docs/pages/resources/stainless-comparison-full.mdx index df4332a8..12359531 100644 --- a/fern/products/docs/pages/resources/stainless-comparison-full.mdx +++ b/fern/products/docs/pages/resources/stainless-comparison-full.mdx @@ -5,11 +5,13 @@ description: Comprehensive enterprise feature comparison between Stainless Docs # Stainless Docs vs Fern Docs: Enterprise Feature Comparison -## Executive Summary +## Executive summary + Fern Docs is a production-ready, enterprise-grade documentation platform with comprehensive features for large-scale API documentation, while Stainless Docs Platform remains in early access with significant feature gaps for enterprise deployments. + -**Key Enterprise Advantages of Fern:** +**Key enterprise advantages of Fern:** 1. **Production Maturity**: Fern is production-ready and battle-tested, while Stainless explicitly warns of "breaking changes before 1.0" in their early access phase. @@ -33,9 +35,10 @@ Fern Docs is a production-ready, enterprise-grade documentation platform with co --- -## Detailed Feature Comparison +## Detailed feature comparison -### 1. Platform Maturity and Stability + + | Feature | Fern Docs | Stainless Docs | |---------|-----------|----------------| @@ -50,9 +53,9 @@ Fern Docs is a production-ready, enterprise-grade documentation platform with co **Gap Analysis:** Stainless is not ready for enterprise production deployments where API stability and backward compatibility are critical. Fern's production-ready status makes it suitable for mission-critical documentation. ---- + -### 2. Content Authoring and Governance + | Feature | Fern Docs | Stainless Docs | |---------|-----------|----------------| @@ -70,9 +73,9 @@ Fern Docs is a production-ready, enterprise-grade documentation platform with co **Gap Analysis:** Stainless requires all authors to use Git workflows and code editors, limiting collaboration to technical team members. Fern's visual editor democratizes documentation authoring, enabling technical writers, product managers, and support teams to contribute without Git expertise. ---- + -### 3. API Reference and Interactive Testing + | Feature | Fern Docs | Stainless Docs | |---------|-----------|----------------| @@ -91,9 +94,9 @@ Fern Docs is a production-ready, enterprise-grade documentation platform with co **Gap Analysis:** Stainless lacks an interactive API testing environment, forcing developers to use external tools like Postman or curl. Fern's integrated API Explorer reduces friction and enables developers to test endpoints without leaving the documentation, with automatic credential injection for authenticated users. ---- + -### 4. RBAC, Versioning, and Multi-Product Support + | Feature | Fern Docs | Stainless Docs | |---------|-----------|----------------| @@ -117,9 +120,9 @@ Fern Docs is a production-ready, enterprise-grade documentation platform with co Fern's RBAC and versioning capabilities are essential for enterprises with complex API portfolios and diverse user bases. ---- + -### 5. AI-Powered Search and Assistance + | Feature | Fern Docs | Stainless Docs | |---------|-----------|----------------| @@ -147,9 +150,9 @@ Fern's RBAC and versioning capabilities are essential for enterprises with compl Stainless offers basic RAG search without the operational controls needed for enterprise deployments where answer accuracy and compliance are critical. ---- + -### 6. Authentication and Security + | Feature | Fern Docs | Stainless Docs | |---------|-----------|----------------| @@ -169,9 +172,9 @@ Stainless offers basic RAG search without the operational controls needed for en - Compliance with security policies requiring authenticated documentation access - Integration with existing identity providers (Okta, Azure AD, etc.) ---- + -### 7. Hosting and Deployment + | Feature | Fern Docs | Stainless Docs | |---------|-----------|----------------| @@ -197,9 +200,9 @@ Stainless offers basic RAG search without the operational controls needed for en Fern's self-hosted Docker container includes all necessary services (PostgreSQL, MinIO, MeiliSearch, FDR, Next.js UI), making it suitable for regulated industries (healthcare, finance, government) that require on-premises deployment with full data sovereignty. ---- + -### 8. Redirects, SEO, and Large-Site Operations + | Feature | Fern Docs | Stainless Docs | |---------|-----------|----------------| @@ -224,9 +227,9 @@ Fern's self-hosted Docker container includes all necessary services (PostgreSQL, Stainless lacks documented redirect capabilities, making it unsuitable for migrations or large-scale content reorganization. ---- + -### 9. Analytics and Observability + | Feature | Fern Docs | Stainless Docs | |---------|-----------|----------------| @@ -251,9 +254,9 @@ Stainless lacks documented redirect capabilities, making it unsuitable for migra This data-driven approach enables continuous documentation improvement. Stainless lacks documented analytics capabilities. ---- + -### 10. Extensibility and Integrations + | Feature | Fern Docs | Stainless Docs | |---------|-----------|----------------| @@ -278,9 +281,12 @@ This data-driven approach enables continuous documentation improvement. Stainles Stainless emphasizes Astro's ecosystem but lacks the enterprise integrations Fern provides. + + + --- -## Technology Stack Comparison +## Technology stack comparison ### Fern Docs - **Frontend**: Next.js (React) with SSR/SSG @@ -312,9 +318,10 @@ Stainless emphasizes Astro's ecosystem but lacks the enterprise integrations Fer --- -## Use Case Recommendations +## Use case recommendations -### Choose Fern Docs When: + + 1. **Enterprise Requirements**: You need RBAC, SSO, versioning, or multi-product documentation 2. **Regulated Industries**: You require self-hosted deployment with full data sovereignty 3. **Interactive Testing**: Developers need to test APIs directly in documentation @@ -326,7 +333,9 @@ Stainless emphasizes Astro's ecosystem but lacks the enterprise integrations Fer 9. **Production Stability**: You need a stable, battle-tested platform with backward compatibility 10. **Comprehensive Support**: You want white-glove migration and ongoing support -### Choose Stainless Docs When: + + + 1. **Early Adopter**: You're comfortable with early access software and breaking changes 2. **Simple Documentation**: You have straightforward documentation needs without versioning or RBAC 3. **Astro Expertise**: Your team prefers Astro and wants deep customization control @@ -338,9 +347,12 @@ Stainless emphasizes Astro's ecosystem but lacks the enterprise integrations Fer 9. **Cloudflare Preference**: You're committed to Cloudflare's ecosystem 10. **Patience for Maturity**: You can wait for the platform to reach 1.0 stability + + + --- -## Migration Considerations +## Migration considerations ### Migrating from Stainless to Fern - **Effort**: Medium - Content can be migrated from MDX/Markdoc to Fern MDX @@ -374,11 +386,13 @@ Stainless emphasizes Astro's ecosystem but lacks the enterprise integrations Fer ## Conclusion -Fern Docs is the clear choice for enterprise organizations requiring production-ready documentation with advanced features like RBAC, versioning, interactive API testing, visual editing, enterprise SSO, and full-stack self-hosting. The platform's maturity, comprehensive feature set, and robust infrastructure make it suitable for mission-critical documentation at scale. + +**Fern Docs is the clear choice for enterprise organizations** requiring production-ready documentation with advanced features like RBAC, versioning, interactive API testing, visual editing, enterprise SSO, and full-stack self-hosting. The platform's maturity, comprehensive feature set, and robust infrastructure make it suitable for mission-critical documentation at scale. -Stainless Docs Platform shows promise with its Astro-based architecture and SDK-native approach, but remains in early access with significant feature gaps for enterprise deployments. Organizations should wait for Stainless to reach production maturity before considering it for critical documentation needs. +**Stainless Docs Platform shows promise** with its Astro-based architecture and SDK-native approach, but remains in early access with significant feature gaps for enterprise deployments. Organizations should wait for Stainless to reach production maturity before considering it for critical documentation needs. -For enterprises evaluating documentation platforms today, Fern Docs provides the stability, features, and support required for successful API documentation programs. +**For enterprises evaluating documentation platforms today**, Fern Docs provides the stability, features, and support required for successful API documentation programs. + --- diff --git a/fern/products/docs/pages/resources/stainless-comparison-summary.mdx b/fern/products/docs/pages/resources/stainless-comparison-summary.mdx index 850793d0..6950a1c9 100644 --- a/fern/products/docs/pages/resources/stainless-comparison-summary.mdx +++ b/fern/products/docs/pages/resources/stainless-comparison-summary.mdx @@ -5,63 +5,95 @@ description: Concise comparison highlighting enterprise feature gaps between Sta # Stainless Docs vs Fern Docs: Quick comparison -## TL;DR - + **Fern Docs** is production-ready and enterprise-grade with comprehensive features. **Stainless Docs** is in early access with significant feature gaps for enterprise deployments. + --- ## Top 10 enterprise gaps where Stainless falls short -### 1. Platform maturity ⚠️ -- **Stainless**: Early access, "expect breaking changes before 1.0" -- **Fern**: Production-ready, stable, widely deployed -- **Impact**: Stainless not suitable for mission-critical documentation - -### 2. Fern Editor & non-technical authors ❌ -- **Stainless**: Git-only workflow, requires technical expertise -- **Fern**: WYSIWYG Fern Editor + GitHub App for writers/PMs -- **Impact**: Stainless limits collaboration to engineers only - -### 3. RBAC & audience filtering ❌ -- **Stainless**: No documented support -- **Fern**: Content gating by audience (internal vs. public, by tier) -- **Impact**: Can't show different docs to different user groups - -### 4. API versioning ❌ -- **Stainless**: No documented versioning system -- **Fern**: First-class versioning with availability states -- **Impact**: Can't maintain multiple API versions simultaneously - -### 5. Interactive API explorer ❌ -- **Stainless**: No documented playground -- **Fern**: Full API testing with auto-populated credentials, WebSocket support -- **Impact**: Developers must use external tools (Postman, curl) - -### 6. Enterprise SSO ❌ -- **Stainless**: API keys for their service only -- **Fern**: WorkOS integration (SAML/OIDC/SCIM) -- **Impact**: Can't require authentication for viewing docs - -### 7. Full-stack self-hosting ❌ -- **Stainless**: Static files only -- **Fern**: Complete Docker container (DB, storage, search, UI) -- **Impact**: Not suitable for regulated industries requiring on-prem - -### 8. AI operational controls ❌ -- **Stainless**: Basic RAG search -- **Fern**: Guidance docs, Documents API, Slack bot, MCP server, analytics -- **Impact**: Can't control AI answers or add custom knowledge sources - -### 9. Multi-spec support ⚠️ -- **Stainless**: OpenAPI + Stainless config only -- **Fern**: OpenAPI, AsyncAPI, gRPC, OpenRPC, Fern spec -- **Impact**: Limited to REST APIs, no event-driven or RPC support - -### 10. Advanced redirects & SEO ❌ -- **Stainless**: No documented redirect system -- **Fern**: 299+ redirect rules with pattern matching -- **Impact**: Difficult to migrate or restructure large sites + + + **Stainless**: Early access, "expect breaking changes before 1.0" + + **Fern**: Production-ready, stable, widely deployed + + **Impact**: Stainless not suitable for mission-critical documentation + + + + **Stainless**: Git-only workflow, requires technical expertise + + **Fern**: WYSIWYG Fern Editor + GitHub App for writers/PMs + + **Impact**: Stainless limits collaboration to engineers only + + + + **Stainless**: No documented support + + **Fern**: Content gating by audience (internal vs. public, by tier) + + **Impact**: Can't show different docs to different user groups + + + + **Stainless**: No documented versioning system + + **Fern**: First-class versioning with availability states + + **Impact**: Can't maintain multiple API versions simultaneously + + + + **Stainless**: No documented playground + + **Fern**: Full API testing with auto-populated credentials, WebSocket support + + **Impact**: Developers must use external tools (Postman, curl) + + + + **Stainless**: API keys for their service only + + **Fern**: WorkOS integration (SAML/OIDC/SCIM) + + **Impact**: Can't require authentication for viewing docs + + + + **Stainless**: Static files only + + **Fern**: Complete Docker container (DB, storage, search, UI) + + **Impact**: Not suitable for regulated industries requiring on-prem + + + + **Stainless**: Basic RAG search + + **Fern**: Guidance docs, Documents API, Slack bot, MCP server, analytics + + **Impact**: Can't control AI answers or add custom knowledge sources + + + + **Stainless**: OpenAPI + Stainless config only + + **Fern**: OpenAPI, AsyncAPI, gRPC, OpenRPC, Fern spec + + **Impact**: Limited to REST APIs, no event-driven or RPC support + + + + **Stainless**: No documented redirect system + + **Fern**: 299+ redirect rules with pattern matching + + **Impact**: Difficult to migrate or restructure large sites + + --- @@ -86,49 +118,59 @@ description: Concise comparison highlighting enterprise feature gaps between Sta ## When to choose each -### Choose Fern when: -- ✅ Enterprise requirements (RBAC, SSO, versioning) -- ✅ Regulated industries (self-hosted required) -- ✅ Non-technical authors need to contribute -- ✅ Interactive API testing is important -- ✅ Production stability is critical -- ✅ Advanced AI with operational controls -- ✅ Large-scale documentation (100+ pages) -- ✅ Multi-product or multi-version APIs - -### Choose Stainless when: -- ⚠️ Comfortable with early access software -- ⚠️ Simple docs without versioning/RBAC -- ⚠️ All authors are technical (Git comfortable) -- ⚠️ Static hosting is sufficient -- ⚠️ Astro expertise and preference -- ⚠️ Can wait for 1.0 stability + + + Enterprise requirements (RBAC, SSO, versioning) + Regulated industries (self-hosted required) + Non-technical authors need to contribute + Interactive API testing is important + Production stability is critical + Advanced AI with operational controls + Large-scale documentation (100+ pages) + Multi-product or multi-version APIs + + + + Comfortable with early access software + Simple docs without versioning/RBAC + All authors are technical (Git comfortable) + Static hosting is sufficient + Astro expertise and preference + Can wait for 1.0 stability + + --- ## Key links -### Fern resources -- **Overview**: https://buildwithfern.com/learn/docs/ -- **Quickstart**: https://buildwithfern.com/learn/docs/getting-started/quickstart -- **Fern Editor**: https://buildwithfern.com/learn/docs/writing-content/fern-editor -- **API Explorer**: https://buildwithfern.com/learn/docs/api-references/api-explorer/overview -- **Self-Hosted**: https://buildwithfern.com/learn/docs/self-hosted/overview -- **Ask Fern AI**: https://buildwithfern.com/learn/ask-fern/ -- **Contact**: https://buildwithfern.com/contact - -### Stainless resources -- **Overview**: https://www.stainless.com/docs/docs-platform/ -- **Early Access Warning**: https://www.stainless.com/docs/docs-platform/ (top of page) -- **Interest Form**: https://www.stainless.com/products/docs + + + - [Overview](https://buildwithfern.com/learn/docs/) + - [Quickstart](https://buildwithfern.com/learn/docs/getting-started/quickstart) + - [Fern Editor](https://buildwithfern.com/learn/docs/writing-content/fern-editor) + - [API Explorer](https://buildwithfern.com/learn/docs/api-references/api-explorer/overview) + - [Self-Hosted](https://buildwithfern.com/learn/docs/self-hosted/overview) + - [Ask Fern AI](https://buildwithfern.com/learn/ask-fern/) + - [Contact](https://buildwithfern.com/contact) + + + + - [Overview](https://www.stainless.com/docs/docs-platform/) + - [Early Access Warning](https://www.stainless.com/docs/docs-platform/) (top of page) + - [Interest Form](https://www.stainless.com/products/docs) + + --- ## Bottom line + **Fern Docs** is the enterprise-ready choice with production stability, comprehensive features, and robust infrastructure. **Stainless Docs** shows promise but remains in early access with critical feature gaps for enterprise deployments. For organizations evaluating documentation platforms today, Fern provides the maturity, features, and support required for mission-critical API documentation. + --- From 48715f1fd4edfe61a3e1ce8ea4f48e3618290b6b Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 6 Nov 2025 15:13:59 -0500 Subject: [PATCH 5/6] condense/clean up page --- fern/products/docs/docs.yml | 12 +- .../resources/stainless-comparison-full.mdx | 420 ------------------ .../stainless-comparison-summary.mdx | 177 -------- .../pages/resources/stainless-comparison.mdx | 163 +++++++ 4 files changed, 167 insertions(+), 605 deletions(-) delete mode 100644 fern/products/docs/pages/resources/stainless-comparison-full.mdx delete mode 100644 fern/products/docs/pages/resources/stainless-comparison-summary.mdx create mode 100644 fern/products/docs/pages/resources/stainless-comparison.mdx diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index 0059c4a7..e0c269b5 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -289,13 +289,9 @@ navigation: path: ./pages/developer-tools/view-markdown.mdx - section: Resources collapsed: true + hidden: true contents: - - page: Stainless vs Fern comparison (full) - path: ./pages/resources/stainless-comparison-full.mdx - slug: stainless-comparison-full - hidden: true - - page: Stainless vs Fern comparison (summary) - path: ./pages/resources/stainless-comparison-summary.mdx - slug: stainless-comparison-summary - hidden: true + - page: Stainless vs. Fern + path: ./pages/resources/stainless-comparison.mdx + slug: stainless-comparison diff --git a/fern/products/docs/pages/resources/stainless-comparison-full.mdx b/fern/products/docs/pages/resources/stainless-comparison-full.mdx deleted file mode 100644 index 12359531..00000000 --- a/fern/products/docs/pages/resources/stainless-comparison-full.mdx +++ /dev/null @@ -1,420 +0,0 @@ ---- -title: Stainless Docs vs Fern Docs - Detailed comparison -description: Comprehensive enterprise feature comparison between Stainless Docs and Fern Docs platforms ---- - -# Stainless Docs vs Fern Docs: Enterprise Feature Comparison - -## Executive summary - - -Fern Docs is a production-ready, enterprise-grade documentation platform with comprehensive features for large-scale API documentation, while Stainless Docs Platform remains in early access with significant feature gaps for enterprise deployments. - - -**Key enterprise advantages of Fern:** - -1. **Production Maturity**: Fern is production-ready and battle-tested, while Stainless explicitly warns of "breaking changes before 1.0" in their early access phase. - -2. **Visual Editor & Governance**: Fern provides a WYSIWYG visual editor with GitHub App integration for non-technical authors, enabling broader team collaboration. Stainless only supports Git-based workflows requiring technical expertise. - -3. **RBAC & Multi-Instance Deployment**: Fern offers audience-based content filtering (RBAC) to show/hide products, versions, and pages across different instances (internal vs. public). Stainless has no documented support for this critical enterprise requirement. - -4. **API Versioning & Multi-Product Sites**: Fern provides first-class API versioning with availability states and multi-product documentation in a single site. Stainless lacks documented versioning capabilities. - -5. **Interactive API Explorer**: Fern includes a built-in API Explorer for testing endpoints directly in documentation with environment/auth support, auto-populated credentials, and WebSocket testing. Stainless has no documented API playground. - -6. **Enterprise Authentication**: Fern integrates with WorkOS for enterprise SSO (SAML/OIDC). Stainless authentication is limited to API keys for their service, not end-user SSO. - -7. **Full-Stack Self-Hosting**: Fern offers a complete Docker container with database, object storage, search, and UI for regulated environments. Stainless only supports static file hosting. - -8. **Advanced AI Capabilities**: Fern provides Ask Fern chatbot, guidance documents, Documents API, Slack bot, MCP server auto-generation, and analytics/insights. Stainless offers basic RAG search without operational controls. - -9. **Multi-Spec Support**: Fern supports OpenAPI, AsyncAPI, gRPC, OpenRPC, and Fern spec. Stainless only supports OpenAPI + Stainless config. - -10. **Enterprise Infrastructure**: Fern runs on AWS VPC with PostgreSQL, Redis, S3, and integrates with Algolia, PostHog, TurboPuffer. Stainless emphasizes Cloudflare static hosting. - ---- - -## Detailed feature comparison - - - - -| Feature | Fern Docs | Stainless Docs | -|---------|-----------|----------------| -| **Production Status** | ✅ Production-ready, stable | ⚠️ Early access with breaking changes expected | -| **API Stability** | ✅ Stable CLI/docs pipeline | ❌ "Expect breaking changes to APIs before 1.0" | -| **Enterprise Deployments** | ✅ Widely deployed (ElevenLabs, Webflow, Hume AI, etc.) | ⚠️ Limited production usage | -| **Documentation Completeness** | ✅ Comprehensive (11,947 lines) | ⚠️ Basic documentation (limited pages) | - -**Citations:** -- Stainless: https://www.stainless.com/docs/docs-platform/ - "The Stainless Docs Platform is currently in early access. Expect breaking changes to APIs before 1.0." -- Fern: https://buildwithfern.com/learn/docs/getting-started/quickstart - -**Gap Analysis:** Stainless is not ready for enterprise production deployments where API stability and backward compatibility are critical. Fern's production-ready status makes it suitable for mission-critical documentation. - - - - - -| Feature | Fern Docs | Stainless Docs | -|---------|-----------|----------------| -| **Visual WYSIWYG Editor** | ✅ Fern Editor with Tiptap | ❌ Not documented | -| **GitHub App Integration** | ✅ Automatic PR creation | ❌ Not documented | -| **Non-Technical Author Support** | ✅ Visual editor for writers | ❌ Requires Git/code knowledge | -| **Dashboard Management** | ✅ Org members, repos, domains | ⚠️ Basic dashboard for API keys | -| **Content Format** | ✅ MDX with React components | ✅ MDX/Markdoc | -| **Markdown Partials** | ✅ Snippets system | ✅ Markdown partials | - -**Citations:** -- Fern Editor: https://buildwithfern.com/learn/docs/writing-content/fern-editor -- Fern Dashboard: https://dashboard.buildwithfern.com -- Stainless: https://www.stainless.com/docs/docs-platform/ - No visual editor mentioned - -**Gap Analysis:** Stainless requires all authors to use Git workflows and code editors, limiting collaboration to technical team members. Fern's visual editor democratizes documentation authoring, enabling technical writers, product managers, and support teams to contribute without Git expertise. - - - - - -| Feature | Fern Docs | Stainless Docs | -|---------|-----------|----------------| -| **Interactive API Explorer** | ✅ Full playground with auth | ❌ Not documented | -| **Auto-Populated Credentials** | ✅ When authenticated | ❌ Not documented | -| **WebSocket Testing** | ✅ Real-time testing | ❌ Not documented | -| **Audio Streaming Support** | ✅ Stream audio in explorer | ❌ Not documented | -| **Environment Switching** | ✅ Production/Sandbox toggle | ❌ Not documented | -| **Language-Specific SDK Docs** | ✅ Multi-language support | ✅ Language-specific pages | -| **Spec Format Support** | ✅ OpenAPI, AsyncAPI, gRPC, OpenRPC, Fern | ⚠️ OpenAPI + Stainless config only | - -**Citations:** -- Fern API Explorer: https://buildwithfern.com/learn/docs/api-references/api-explorer/overview -- Fern Multi-Spec: https://buildwithfern.com/learn/docs/api-references/generate-api-ref -- Stainless: https://www.stainless.com/docs/docs-platform/api-and-sdk-reference/overview/ - No API playground mentioned - -**Gap Analysis:** Stainless lacks an interactive API testing environment, forcing developers to use external tools like Postman or curl. Fern's integrated API Explorer reduces friction and enables developers to test endpoints without leaving the documentation, with automatic credential injection for authenticated users. - - - - - -| Feature | Fern Docs | Stainless Docs | -|---------|-----------|----------------| -| **Audience Filtering (RBAC)** | ✅ Content gating by audience | ❌ Not documented | -| **Multi-Instance Deployment** | ✅ Internal vs. public sites | ❌ Not documented | -| **API Versioning** | ✅ Version management with availability states | ❌ Not documented | -| **Multi-Product Documentation** | ✅ Multiple products in one site | ❌ Not documented | -| **Version-Specific Pages** | ✅ Per-version content | ❌ Not documented | -| **Namespace Organization** | ✅ Organized by product/version | ⚠️ Basic tabs (Guides/Reference) | - -**Citations:** -- Fern Audiences: https://buildwithfern.com/learn/docs/configuration/what-is-docs-yml (audiences section) -- Fern Versions: https://buildwithfern.com/learn/docs/configuration/what-is-docs-yml (versions section) -- Stainless Navigation: https://www.stainless.com/docs/docs-platform/navigation/ - Only basic tabs, no versioning - -**Gap Analysis:** Stainless cannot support common enterprise scenarios like: -- Showing different documentation to internal vs. external users -- Maintaining multiple API versions with deprecation notices -- Hosting documentation for multiple products in a unified site -- Controlling content visibility based on customer tier or role - -Fern's RBAC and versioning capabilities are essential for enterprises with complex API portfolios and diverse user bases. - - - - - -| Feature | Fern Docs | Stainless Docs | -|---------|-----------|----------------| -| **AI Chatbot** | ✅ Ask Fern with Claude/Cohere | ✅ RAG-based Q&A | -| **Guidance Documents** | ✅ Override AI responses | ❌ Not documented | -| **Documents API** | ✅ Custom knowledge sources | ❌ Not documented | -| **Slack Bot Integration** | ✅ `/fern` command | ❌ Not documented | -| **MCP Server** | ✅ Auto-generated for AI clients | ❌ Not documented | -| **Analytics & Insights** | ✅ Content gap identification | ❌ Not documented | -| **Vector Search** | ✅ TurboPuffer integration | ⚠️ Metadata-driven indexing | -| **Faceted Search** | ✅ By language, product, version | ✅ By language, resource type | -| **LLM-Friendly Format** | ✅ /llms.txt and /llms-full.txt | ✅ .md extension on URLs | - -**Citations:** -- Ask Fern: https://buildwithfern.com/learn/ask-fern/getting-started/what-is-ask-fern -- Fern MCP Server: https://buildwithfern.com/learn/docs/ai-features/mcp-server -- Fern llms.txt: https://buildwithfern.com/learn/docs/seo/llms-txt -- Stainless Search: https://www.stainless.com/docs/docs-platform/ - Basic RAG, no operational controls - -**Gap Analysis:** While both platforms offer AI-powered search, Fern provides enterprise-grade operational controls: -- **Guidance documents** let you prescribe exact answers for sensitive topics -- **Documents API** enables adding internal knowledge bases and support articles -- **Analytics** identify documentation gaps based on unanswered questions -- **MCP server** enables AI coding assistants to access your docs programmatically - -Stainless offers basic RAG search without the operational controls needed for enterprise deployments where answer accuracy and compliance are critical. - - - - - -| Feature | Fern Docs | Stainless Docs | -|---------|-----------|----------------| -| **Enterprise SSO** | ✅ WorkOS (SAML/OIDC/SCIM) | ❌ Not documented | -| **Role-Based Access** | ✅ Audience-based content gating | ❌ Not documented | -| **Authenticated Pages** | ✅ Login-protected documentation | ❌ Not documented | -| **API Key Management** | ✅ Auto-populate in explorer | ⚠️ API keys for Stainless service only | -| **JWT Token Support** | ✅ Automatic extraction | ❌ Not documented | - -**Citations:** -- Fern WorkOS: https://buildwithfern.com/learn/docs/getting-started/how-fern-docs-work (WorkOS integration) -- Stainless Auth: https://www.stainless.com/docs/docs-platform/advanced/stainless-authentication/ - Only API keys for their service - -**Gap Analysis:** Stainless's "authentication" refers to API keys for accessing their documentation generation service, not end-user authentication for viewing documentation. Fern's WorkOS integration provides enterprise SSO, enabling: -- SAML/OIDC authentication for employees and customers -- Role-based content visibility -- Compliance with security policies requiring authenticated documentation access -- Integration with existing identity providers (Okta, Azure AD, etc.) - - - - - -| Feature | Fern Docs | Stainless Docs | -|---------|-----------|----------------| -| **Cloud Hosting** | ✅ Vercel with AWS VPC backend | ✅ Cloudflare (default) | -| **Self-Hosted Full Stack** | ✅ Docker with DB, storage, search | ❌ Static files only | -| **Database Included** | ✅ PostgreSQL in self-hosted | ❌ Not applicable | -| **Object Storage** | ✅ S3/MinIO in self-hosted | ❌ Not applicable | -| **Search Engine** | ✅ MeiliSearch in self-hosted | ❌ Not applicable | -| **Custom Domains** | ✅ Full support | ✅ Full support | -| **CDN Integration** | ✅ Cloudflare + Vercel Edge | ✅ Cloudflare | - -**Citations:** -- Fern Self-Hosted: https://buildwithfern.com/learn/docs/self-hosted/overview -- Fern Architecture: https://buildwithfern.com/learn/docs/getting-started/how-fern-docs-work -- Stainless Hosting: https://www.stainless.com/docs/docs-platform/hosting-and-deploys/ - Static hosting only - -**Gap Analysis:** Stainless can only deploy static HTML/CSS/JS files, requiring customers to provide their own infrastructure for: -- Search indexing and querying -- User authentication and session management -- Analytics and usage tracking -- Dynamic content generation -- API proxy for CORS - -Fern's self-hosted Docker container includes all necessary services (PostgreSQL, MinIO, MeiliSearch, FDR, Next.js UI), making it suitable for regulated industries (healthcare, finance, government) that require on-premises deployment with full data sovereignty. - - - - - -| Feature | Fern Docs | Stainless Docs | -|---------|-----------|----------------| -| **Advanced Redirects** | ✅ 299+ rules with pattern matching | ❌ Not documented | -| **Redirect Parameters** | ✅ `:slug` and `:splat` support | ❌ Not documented | -| **Permanent Redirects** | ✅ 301/302 support | ❌ Not documented | -| **SEO Optimization** | ✅ Meta tags, JSON-LD, RSS | ✅ Basic meta tags | -| **Sitemap Generation** | ✅ Automatic | ✅ Automatic (assumed) | -| **robots.txt** | ✅ Automatic | ✅ Automatic (assumed) | -| **Social Sharing** | ✅ OG images, Twitter cards | ⚠️ Basic support | - -**Citations:** -- Fern Redirects: https://buildwithfern.com/learn/docs/configuration/what-is-docs-yml (redirects section) -- Fern SEO: https://buildwithfern.com/learn/docs/seo/llms-txt -- Stainless: No redirect documentation found - -**Gap Analysis:** Large documentation sites require redirect management when restructuring content, deprecating pages, or migrating from other platforms. Fern's redirect system supports: -- Pattern matching with wildcards -- Parameter preservation across redirects -- Permanent vs. temporary redirects -- Hundreds of rules managed in `docs.yml` - -Stainless lacks documented redirect capabilities, making it unsuitable for migrations or large-scale content reorganization. - - - - - -| Feature | Fern Docs | Stainless Docs | -|---------|-----------|----------------| -| **Analytics Integration** | ✅ PostHog, Google Analytics | ❌ Not documented | -| **Search Analytics** | ✅ Query tracking and insights | ❌ Not documented | -| **AI Chat Analytics** | ✅ Question/answer tracking | ❌ Not documented | -| **Content Gap Identification** | ✅ Unanswered questions report | ❌ Not documented | -| **Custom Event Tracking** | ✅ Via PostHog | ❌ Not documented | -| **Performance Monitoring** | ✅ Vercel Analytics | ⚠️ Cloudflare Analytics | - -**Citations:** -- Fern Analytics: https://buildwithfern.com/learn/docs/getting-started/how-fern-docs-work (PostHog integration) -- Fern Insights: https://buildwithfern.com/learn/ask-fern/ (insights section) -- Stainless: No analytics documentation found - -**Gap Analysis:** Fern provides comprehensive analytics to understand documentation usage: -- Which pages are most/least visited -- What users are searching for -- Which questions Ask Fern cannot answer (content gaps) -- User journey through documentation -- API Explorer usage patterns - -This data-driven approach enables continuous documentation improvement. Stainless lacks documented analytics capabilities. - - - - - -| Feature | Fern Docs | Stainless Docs | -|---------|-----------|----------------| -| **Component Library** | ✅ 30+ pre-built components | ⚠️ Standard library | -| **Custom React Components** | ✅ Full support | ✅ Via Astro | -| **Custom CSS/JS** | ✅ Full support | ✅ Full support | -| **Third-Party Integrations** | ✅ Algolia, PostHog, WorkOS, etc. | ⚠️ Astro ecosystem | -| **MCP Server** | ✅ Auto-generated | ❌ Not documented | -| **Webhook Support** | ✅ For AI chat events | ❌ Not documented | -| **API for Programmatic Updates** | ✅ FDR API | ❌ Not documented | - -**Citations:** -- Fern Components: https://buildwithfern.com/learn/docs/writing-content/components/overview -- Fern Custom CSS: https://buildwithfern.com/learn/docs/customization/custom-css-js -- Stainless Customization: https://www.stainless.com/docs/docs-platform/customization/styles-and-fonts/ - -**Gap Analysis:** Both platforms support customization, but Fern provides deeper integration capabilities: -- **MCP server** enables AI coding assistants (Cursor, Copilot) to access documentation -- **Webhooks** enable custom workflows triggered by AI chat events -- **FDR API** enables programmatic documentation updates -- **30+ components** provide rich documentation experiences out-of-the-box - -Stainless emphasizes Astro's ecosystem but lacks the enterprise integrations Fern provides. - - - - ---- - -## Technology stack comparison - -### Fern Docs -- **Frontend**: Next.js (React) with SSR/SSG -- **Backend**: Node.js/Express (FDR) on AWS VPC -- **Database**: PostgreSQL -- **Cache**: Redis, Vercel KV (Upstash) -- **Storage**: S3 (AWS/MinIO) -- **Search**: Algolia, MeiliSearch (self-hosted) -- **Vector DB**: TurboPuffer -- **AI**: Bedrock, Claude, Cohere -- **Auth**: WorkOS -- **CDN**: Cloudflare + Vercel Edge -- **Analytics**: PostHog -- **Deployment**: Vercel, Docker (self-hosted) - -### Stainless Docs -- **Frontend**: Astro (static site generator) -- **Backend**: Stainless API service -- **Database**: Not applicable (static) -- **Cache**: Cloudflare CDN -- **Storage**: Not applicable (static) -- **Search**: Metadata-driven indexing -- **Vector DB**: Not documented -- **AI**: RAG with LLM (provider not specified) -- **Auth**: API keys (for Stainless service) -- **CDN**: Cloudflare (default) -- **Analytics**: Not documented -- **Deployment**: Cloudflare, any static host - ---- - -## Use case recommendations - - - -1. **Enterprise Requirements**: You need RBAC, SSO, versioning, or multi-product documentation -2. **Regulated Industries**: You require self-hosted deployment with full data sovereignty -3. **Interactive Testing**: Developers need to test APIs directly in documentation -4. **Non-Technical Authors**: Technical writers and product managers need to contribute without Git -5. **Advanced AI**: You need operational controls over AI answers (guidance docs, custom sources) -6. **Large-Scale Sites**: You're managing complex documentation with hundreds of pages and redirects -7. **Analytics-Driven**: You want data on documentation usage and content gaps -8. **Multi-Spec Support**: You use AsyncAPI, gRPC, or OpenRPC in addition to OpenAPI -9. **Production Stability**: You need a stable, battle-tested platform with backward compatibility -10. **Comprehensive Support**: You want white-glove migration and ongoing support - - - - -1. **Early Adopter**: You're comfortable with early access software and breaking changes -2. **Simple Documentation**: You have straightforward documentation needs without versioning or RBAC -3. **Astro Expertise**: Your team prefers Astro and wants deep customization control -4. **Static Hosting**: You only need static file hosting without backend services -5. **SDK-Centric**: Your primary focus is SDK documentation generated from Stainless SDKs -6. **Technical Team**: All documentation authors are comfortable with Git workflows -7. **Basic Search**: Metadata-driven search without operational AI controls is sufficient -8. **Cost-Sensitive**: You want to minimize hosting costs with static files -9. **Cloudflare Preference**: You're committed to Cloudflare's ecosystem -10. **Patience for Maturity**: You can wait for the platform to reach 1.0 stability - - - - ---- - -## Migration considerations - -### Migrating from Stainless to Fern -- **Effort**: Medium - Content can be migrated from MDX/Markdoc to Fern MDX -- **OpenAPI Compatibility**: High - Fern supports OpenAPI specs directly -- **Custom Components**: Requires rewriting Astro components as React components -- **Redirects**: Fern's redirect system can maintain URL compatibility -- **Timeline**: Fern offers white-glove migration service for Enterprise customers - -### Migrating from Other Platforms to Fern -- **Readme.com**: High compatibility, similar component library -- **GitBook**: Medium effort, content structure differs -- **Docusaurus**: Medium effort, React components compatible -- **Mintlify**: High compatibility, similar MDX approach -- **Swagger UI**: Low effort for API reference, need to add guides - ---- - -## Pricing Considerations - -### Fern Docs -- **Starter**: Free tier available -- **Pro**: Usage-based pricing -- **Enterprise**: Custom pricing with white-glove migration, dedicated support, SLA -- **Self-Hosted**: Available for Enterprise customers - -### Stainless Docs -- **Pricing**: Not publicly documented (early access) -- **Requires**: Stainless SDK generation service - ---- - -## Conclusion - - -**Fern Docs is the clear choice for enterprise organizations** requiring production-ready documentation with advanced features like RBAC, versioning, interactive API testing, visual editing, enterprise SSO, and full-stack self-hosting. The platform's maturity, comprehensive feature set, and robust infrastructure make it suitable for mission-critical documentation at scale. - -**Stainless Docs Platform shows promise** with its Astro-based architecture and SDK-native approach, but remains in early access with significant feature gaps for enterprise deployments. Organizations should wait for Stainless to reach production maturity before considering it for critical documentation needs. - -**For enterprises evaluating documentation platforms today**, Fern Docs provides the stability, features, and support required for successful API documentation programs. - - ---- - -## Additional Resources - -### Fern Docs -- **Documentation**: https://buildwithfern.com/learn/docs/ -- **Quickstart**: https://buildwithfern.com/learn/docs/getting-started/quickstart -- **API Explorer**: https://buildwithfern.com/learn/docs/api-references/api-explorer/overview -- **Self-Hosted**: https://buildwithfern.com/learn/docs/self-hosted/overview -- **Ask Fern**: https://buildwithfern.com/learn/ask-fern/ -- **GitHub**: https://github.com/fern-api/fern -- **Contact**: https://buildwithfern.com/contact - -### Stainless Docs -- **Documentation**: https://www.stainless.com/docs/docs-platform/ -- **Quickstart**: https://www.stainless.com/docs/docs-platform/quickstart/ -- **Interest Form**: https://www.stainless.com/products/docs -- **Feedback**: feedback@stainless.com - ---- - -*Document Version: 1.0* -*Last Updated: November 6, 2025* -*Prepared for: Fern Sales Engineering* diff --git a/fern/products/docs/pages/resources/stainless-comparison-summary.mdx b/fern/products/docs/pages/resources/stainless-comparison-summary.mdx deleted file mode 100644 index 6950a1c9..00000000 --- a/fern/products/docs/pages/resources/stainless-comparison-summary.mdx +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: Stainless Docs vs Fern Docs - Quick comparison -description: Concise comparison highlighting enterprise feature gaps between Stainless Docs and Fern Docs ---- - -# Stainless Docs vs Fern Docs: Quick comparison - - -**Fern Docs** is production-ready and enterprise-grade with comprehensive features. **Stainless Docs** is in early access with significant feature gaps for enterprise deployments. - - ---- - -## Top 10 enterprise gaps where Stainless falls short - - - - **Stainless**: Early access, "expect breaking changes before 1.0" - - **Fern**: Production-ready, stable, widely deployed - - **Impact**: Stainless not suitable for mission-critical documentation - - - - **Stainless**: Git-only workflow, requires technical expertise - - **Fern**: WYSIWYG Fern Editor + GitHub App for writers/PMs - - **Impact**: Stainless limits collaboration to engineers only - - - - **Stainless**: No documented support - - **Fern**: Content gating by audience (internal vs. public, by tier) - - **Impact**: Can't show different docs to different user groups - - - - **Stainless**: No documented versioning system - - **Fern**: First-class versioning with availability states - - **Impact**: Can't maintain multiple API versions simultaneously - - - - **Stainless**: No documented playground - - **Fern**: Full API testing with auto-populated credentials, WebSocket support - - **Impact**: Developers must use external tools (Postman, curl) - - - - **Stainless**: API keys for their service only - - **Fern**: WorkOS integration (SAML/OIDC/SCIM) - - **Impact**: Can't require authentication for viewing docs - - - - **Stainless**: Static files only - - **Fern**: Complete Docker container (DB, storage, search, UI) - - **Impact**: Not suitable for regulated industries requiring on-prem - - - - **Stainless**: Basic RAG search - - **Fern**: Guidance docs, Documents API, Slack bot, MCP server, analytics - - **Impact**: Can't control AI answers or add custom knowledge sources - - - - **Stainless**: OpenAPI + Stainless config only - - **Fern**: OpenAPI, AsyncAPI, gRPC, OpenRPC, Fern spec - - **Impact**: Limited to REST APIs, no event-driven or RPC support - - - - **Stainless**: No documented redirect system - - **Fern**: 299+ redirect rules with pattern matching - - **Impact**: Difficult to migrate or restructure large sites - - - ---- - -## Feature matrix - -| Category | Fern | Stainless | -|----------|------|-----------| -| **Maturity** | ✅ Production | ⚠️ Early Access | -| **Fern Editor** | ✅ Yes | ❌ No | -| **API Explorer** | ✅ Yes | ❌ No | -| **RBAC/Audiences** | ✅ Yes | ❌ No | -| **Versioning** | ✅ Yes | ❌ No | -| **Enterprise SSO** | ✅ WorkOS | ❌ No | -| **Self-Hosted** | ✅ Full Stack | ⚠️ Static Only | -| **AI Controls** | ✅ Advanced | ⚠️ Basic | -| **Multi-Spec** | ✅ 5 formats | ⚠️ OpenAPI only | -| **Redirects** | ✅ 299+ rules | ❌ No | -| **Analytics** | ✅ PostHog | ❌ No | -| **Multi-Product** | ✅ Yes | ❌ No | - ---- - -## When to choose each - - - - Enterprise requirements (RBAC, SSO, versioning) - Regulated industries (self-hosted required) - Non-technical authors need to contribute - Interactive API testing is important - Production stability is critical - Advanced AI with operational controls - Large-scale documentation (100+ pages) - Multi-product or multi-version APIs - - - - Comfortable with early access software - Simple docs without versioning/RBAC - All authors are technical (Git comfortable) - Static hosting is sufficient - Astro expertise and preference - Can wait for 1.0 stability - - - ---- - -## Key links - - - - - [Overview](https://buildwithfern.com/learn/docs/) - - [Quickstart](https://buildwithfern.com/learn/docs/getting-started/quickstart) - - [Fern Editor](https://buildwithfern.com/learn/docs/writing-content/fern-editor) - - [API Explorer](https://buildwithfern.com/learn/docs/api-references/api-explorer/overview) - - [Self-Hosted](https://buildwithfern.com/learn/docs/self-hosted/overview) - - [Ask Fern AI](https://buildwithfern.com/learn/ask-fern/) - - [Contact](https://buildwithfern.com/contact) - - - - - [Overview](https://www.stainless.com/docs/docs-platform/) - - [Early Access Warning](https://www.stainless.com/docs/docs-platform/) (top of page) - - [Interest Form](https://www.stainless.com/products/docs) - - - ---- - -## Bottom line - - -**Fern Docs** is the enterprise-ready choice with production stability, comprehensive features, and robust infrastructure. **Stainless Docs** shows promise but remains in early access with critical feature gaps for enterprise deployments. - -For organizations evaluating documentation platforms today, Fern provides the maturity, features, and support required for mission-critical API documentation. - - ---- - -*For detailed analysis, see the [full comparison document](/learn/docs/resources/stainless-comparison-full)* diff --git a/fern/products/docs/pages/resources/stainless-comparison.mdx b/fern/products/docs/pages/resources/stainless-comparison.mdx new file mode 100644 index 00000000..81a5b62d --- /dev/null +++ b/fern/products/docs/pages/resources/stainless-comparison.mdx @@ -0,0 +1,163 @@ +--- +title: Stainless vs. Fern +description: Comprehensive enterprise feature comparison between Stainless Docs and Fern Docs platforms +--- + +## Overview + +Fern is [production-ready](/learn/docs/getting-started/quickstart) with stable APIs and comprehensive enterprise features. Stainless is in [early access](https://www.stainless.com/docs/docs-platform/) with breaking changes expected before 1.0. + +Choose Fern for enterprise requirements, regulated industries, or production-critical documentation. Choose Stainless for simple documentation with Git-only workflows and Astro preference. + +| Capability | Fern | Stainless | +|------------|------|-----------| +| **Maturity** | Production-ready, stable APIs | Early access, breaking changes expected | +| **Authoring** | [Visual editor](/learn/docs/writing-content/fern-editor) + Git | Git only | +| **Enterprise features** | [RBAC](/learn/docs/authentication/rbac), [SSO](/learn/docs/authentication/sso), [versioning](/learn/docs/configuration/what-is-docs-yml) | None | +| **API testing** | [Interactive explorer](/learn/docs/api-references/api-explorer/overview) | None | +| **Deployment** | Cloud + [full-stack self-hosted](/learn/docs/self-hosted/overview) | Static files only | + +## Detailed feature comparison + + + + +Fern is production-ready with stable APIs and backward compatibility. Stainless is in early access with [expected breaking changes](https://www.stainless.com/docs/docs-platform/) before reaching 1.0. + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Production status** | ✅ [Production-ready](/learn/docs/getting-started/quickstart), stable | ⚠️ Early access with breaking changes expected | +| **Enterprise deployments** | ✅ Widely deployed ([ElevenLabs](https://elevenlabs.io/docs), [Webflow](https://developers.webflow.com), [Hume AI](https://dev.hume.ai)) | ⚠️ Limited production usage | + + + + + +Stainless uses Git-based workflows for all content authoring. Fern supports both Git workflows and the [Fern Editor](/learn/docs/writing-content/fern-editor), a browser-based visual editor for technical writers, product managers, and support teams. + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Visual editor** | ✅ [Fern Editor](/learn/docs/writing-content/fern-editor) with GitHub App integration | ❌ None | +| **Content format** | ✅ [MDX](/learn/docs/writing-content/markdown) with React components | ✅ MDX/Markdoc | +| **Reusable content** | ✅ [Snippets system](/learn/docs/writing-content/reusable-snippets) | ✅ Markdown partials | + + + + + +Stainless does not provide an interactive testing environment. Fern's [API Explorer](/learn/docs/api-references/api-explorer/overview) enables in-browser endpoint testing with automatic credential injection. + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **API explorer** | ✅ [Full playground](/learn/docs/api-references/api-explorer/overview) with [auto-populated credentials](/learn/docs/api-references/autopopulate-api-key), WebSocket, and audio streaming support | ❌ None | +| **SDK documentation** | ✅ [Multi-language support](/learn/docs/api-references/sdk-snippets) | ✅ Language-specific pages | +| **API spec formats** | ✅ [OpenAPI, AsyncAPI, gRPC, OpenRPC, Fern](/learn/docs/api-references/generate-api-ref) | ⚠️ OpenAPI + Stainless config only | + + + + + +Stainless does not currently offer audience-specific content filtering, multi-version APIs, or unified multi-product sites. Fern provides [RBAC](/learn/docs/authentication/rbac) and [versioning](/learn/docs/configuration/what-is-docs-yml) capabilities for complex API portfolios. + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **RBAC** | ✅ [Audience-based content filtering](/learn/docs/authentication/rbac) for internal vs. public sites | ❌ None | +| **API versioning** | ✅ [Multi-version support](/learn/docs/configuration/what-is-docs-yml) with availability states and per-version content | ❌ None | +| **Multi-product sites** | ✅ [Multiple products](/learn/docs/configuration/what-is-docs-yml) in unified documentation | ⚠️ Basic tabs (Guides/Reference) | + + + + + +Stainless offers RAG-based search. Fern provides additional AI features including [guidance documents](/learn/ask-fern/), [custom knowledge sources](/learn/ask-fern/), [MCP server](/learn/docs/ai-features/mcp-server), and analytics for operational control. + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **AI chatbot** | ✅ [Ask Fern](/learn/ask-fern/) with Claude/Cohere, [guidance documents](/learn/ask-fern/), and custom knowledge sources | ✅ RAG-based Q&A | +| **MCP server** | ✅ [Auto-generated](/learn/docs/ai-features/mcp-server) for AI coding assistants | ❌ None | +| **AI analytics** | ✅ [Content gap identification](/learn/ask-fern/) and insights | ❌ None | +| **Search** | ✅ Vector search with faceting by language, product, version | ⚠️ Metadata-driven with basic faceting | +| **LLM-friendly format** | ✅ [/llms.txt and /llms-full.txt](/learn/docs/seo/llms-txt) | ✅ .md extension on URLs | + + + + + +Stainless's [authentication](https://www.stainless.com/docs/docs-platform/advanced/stainless-authentication/) focuses on API keys for their service. Fern's [WorkOS integration](/learn/docs/authentication/sso) provides enterprise SSO (SAML/OIDC) for end-user authentication with role-based content visibility. + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Enterprise SSO** | ✅ [WorkOS](/learn/docs/authentication/sso) (SAML/OIDC/SCIM) with [RBAC](/learn/docs/authentication/rbac) | ❌ None | +| **Authenticated pages** | ✅ [Login-protected documentation](/learn/docs/authentication/overview) with [auto-populated credentials](/learn/docs/api-references/autopopulate-api-key) | ⚠️ API keys for Stainless service only | + + + + + +Stainless [deploys static files](https://www.stainless.com/docs/docs-platform/hosting-and-deploys/) to hosting platforms. Fern's [self-hosted Docker](/learn/docs/self-hosted/overview) includes a full stack (PostgreSQL, MinIO, MeiliSearch) for on-premises deployment. + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Cloud hosting** | ✅ [Vercel with AWS VPC backend](/learn/docs/getting-started/publishing-your-docs) | ✅ Cloudflare (default) | +| **Self-hosted** | ✅ [Full-stack Docker](/learn/docs/self-hosted/overview) (PostgreSQL, S3/MinIO, MeiliSearch) | ❌ Static files only | +| **Custom domains** | ✅ [Full support](/learn/docs/getting-started/setting-up-your-domain) | ✅ Full support | + + + + + +Stainless does not currently document redirect capabilities. Fern's [redirect system](/learn/docs/seo/redirects) supports pattern matching and hundreds of rules for content migrations and reorganization. + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Redirects** | ✅ [299+ rules](/learn/docs/seo/redirects) with pattern matching (`:slug`, `:splat`) | ❌ None | +| **SEO optimization** | ✅ [Meta tags, JSON-LD, RSS, OG images, Twitter cards](/learn/docs/seo/metadata) | ✅ Basic meta tags | +| **Sitemap & robots.txt** | ✅ [Automatic generation](/learn/docs/seo/metadata) | ✅ Automatic (assumed) | + + + + + +Stainless does not currently document built-in analytics capabilities. Fern provides [analytics integrations](/learn/docs/integrations/overview) for page visits, search queries, AI chat insights, and user journeys. + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Analytics integrations** | ✅ [PostHog](/learn/docs/integrations/analytics/posthog), [Google Analytics](/learn/docs/integrations/analytics/google), [Segment](/learn/docs/integrations/analytics/segment), [Mixpanel](/learn/docs/integrations/analytics/mixpanel) ([full list](/learn/docs/integrations/overview)) | ❌ None | +| **Documentation insights** | ✅ Search analytics, AI chat tracking, content gap identification | ❌ None | +| **Performance monitoring** | ✅ Vercel Analytics | ⚠️ Cloudflare Analytics | + + + + + +Both platforms support [customization](https://www.stainless.com/docs/docs-platform/customization/styles-and-fonts/), but Fern provides deeper enterprise integrations including [MCP server](/learn/docs/ai-features/mcp-server) for AI assistants, webhooks, and [30+ pre-built components](/learn/docs/writing-content/components/overview). + +| Feature | Fern Docs | Stainless Docs | +|---------|-----------|----------------| +| **Component library** | ✅ [30+ pre-built components](/learn/docs/writing-content/components/overview) ([Accordion](/learn/docs/writing-content/components/accordions), [Callout](/learn/docs/writing-content/components/callouts), [Card](/learn/docs/writing-content/components/cards), [Tabs](/learn/docs/writing-content/components/tabs), etc.) | ⚠️ Standard library | +| **Custom components** | ✅ [React components](/learn/docs/writing-content/custom-react-components) with [custom CSS/JS](/learn/docs/customization/custom-css-js) | ✅ Astro components with custom CSS/JS | +| **Third-party integrations** | ✅ [Algolia, PostHog, WorkOS, Intercom, etc.](/learn/docs/integrations/overview) | ⚠️ Astro ecosystem | +| **Developer APIs** | ✅ [MCP server](/learn/docs/ai-features/mcp-server), webhooks, FDR API | ❌ None | + + + + +## Technology stack comparison + +| Component | Fern Docs | Stainless Docs | +|-----------|-----------|----------------| +| **Frontend** | Next.js (React) with SSR/SSG | Astro (static site generator) | +| **Backend** | Node.js/Express (FDR) on AWS VPC | Stainless API service | +| **Database** | PostgreSQL | Not applicable (static) | +| **Cache** | Redis, Vercel KV (Upstash) | Cloudflare CDN | +| **Storage** | S3 (AWS/MinIO) | Not applicable (static) | +| **Search** | Algolia, MeiliSearch (self-hosted) | Metadata-driven indexing | +| **Vector database** | TurboPuffer | None | +| **AI** | Bedrock, Claude, Cohere | RAG with LLM (provider not specified) | +| **Authentication** | WorkOS | API keys (for Stainless service) | +| **CDN** | Cloudflare + Vercel Edge | Cloudflare | +| **Analytics** | PostHog | None | +| **Deployment** | Vercel, Docker (self-hosted) | Cloudflare, any static host | + + + From d30e23314040b5b5755b18dafd6b990ba7ebc253 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 6 Nov 2025 15:21:20 -0500 Subject: [PATCH 6/6] vale fixes --- .vale.ini | 2 ++ .vale/styles/FernStyles/Acronyms.yml | 9 +++++++++ .../docs/pages/resources/stainless-comparison.mdx | 10 +++++----- 3 files changed, 16 insertions(+), 5 deletions(-) diff --git a/.vale.ini b/.vale.ini index dcc48728..dcf230e6 100644 --- a/.vale.ini +++ b/.vale.ini @@ -27,6 +27,7 @@ Microsoft.Dashes = NO Microsoft.Foreign = NO Microsoft.Plurals = NO Microsoft.Quotes = NO # Mostly just picks up code +Microsoft.Auto = NO # Not relevant for Fern audience Microsoft.GeneralURL = NO @@ -42,6 +43,7 @@ Microsoft.Headings = NO Microsoft.HeadingPunctuation = NO Microsoft.Hyphens = NO Microsoft.We = NO +Microsoft.Avoid = NO diff --git a/.vale/styles/FernStyles/Acronyms.yml b/.vale/styles/FernStyles/Acronyms.yml index 6cca1813..30097e4d 100644 --- a/.vale/styles/FernStyles/Acronyms.yml +++ b/.vale/styles/FernStyles/Acronyms.yml @@ -91,3 +91,12 @@ exceptions: - PNG - AAA - ARIA + - SSO + - RAG + - SCIM + - CDN + - VPC + - RSS + - FDR + - SSR + - SSG diff --git a/fern/products/docs/pages/resources/stainless-comparison.mdx b/fern/products/docs/pages/resources/stainless-comparison.mdx index 81a5b62d..2aae2698 100644 --- a/fern/products/docs/pages/resources/stainless-comparison.mdx +++ b/fern/products/docs/pages/resources/stainless-comparison.mdx @@ -45,11 +45,11 @@ Stainless uses Git-based workflows for all content authoring. Fern supports both -Stainless does not provide an interactive testing environment. Fern's [API Explorer](/learn/docs/api-references/api-explorer/overview) enables in-browser endpoint testing with automatic credential injection. +Stainless doesn't provide an interactive testing environment. Fern's [API Explorer](/learn/docs/api-references/api-explorer/overview) enables in-browser endpoint testing with automatic credential injection. | Feature | Fern Docs | Stainless Docs | |---------|-----------|----------------| -| **API explorer** | ✅ [Full playground](/learn/docs/api-references/api-explorer/overview) with [auto-populated credentials](/learn/docs/api-references/autopopulate-api-key), WebSocket, and audio streaming support | ❌ None | +| **API Explorer** | ✅ [Full playground](/learn/docs/api-references/api-explorer/overview) with [auto-populated credentials](/learn/docs/api-references/autopopulate-api-key), WebSocket, and audio streaming support | ❌ None | | **SDK documentation** | ✅ [Multi-language support](/learn/docs/api-references/sdk-snippets) | ✅ Language-specific pages | | **API spec formats** | ✅ [OpenAPI, AsyncAPI, gRPC, OpenRPC, Fern](/learn/docs/api-references/generate-api-ref) | ⚠️ OpenAPI + Stainless config only | @@ -57,7 +57,7 @@ Stainless does not provide an interactive testing environment. Fern's [API Explo -Stainless does not currently offer audience-specific content filtering, multi-version APIs, or unified multi-product sites. Fern provides [RBAC](/learn/docs/authentication/rbac) and [versioning](/learn/docs/configuration/what-is-docs-yml) capabilities for complex API portfolios. +Stainless doesn't currently offer audience-specific content filtering, multi-version APIs, or unified multi-product sites. Fern provides [RBAC](/learn/docs/authentication/rbac) and [versioning](/learn/docs/configuration/what-is-docs-yml) capabilities for complex API portfolios. | Feature | Fern Docs | Stainless Docs | |---------|-----------|----------------| @@ -106,7 +106,7 @@ Stainless [deploys static files](https://www.stainless.com/docs/docs-platform/ho -Stainless does not currently document redirect capabilities. Fern's [redirect system](/learn/docs/seo/redirects) supports pattern matching and hundreds of rules for content migrations and reorganization. +Stainless doesn't currently document redirect capabilities. Fern's [redirect system](/learn/docs/seo/redirects) supports pattern matching and hundreds of rules for content migrations and reorganization. | Feature | Fern Docs | Stainless Docs | |---------|-----------|----------------| @@ -118,7 +118,7 @@ Stainless does not currently document redirect capabilities. Fern's [redirect sy -Stainless does not currently document built-in analytics capabilities. Fern provides [analytics integrations](/learn/docs/integrations/overview) for page visits, search queries, AI chat insights, and user journeys. +Stainless doesn't currently document built-in analytics capabilities. Fern provides [analytics integrations](/learn/docs/integrations/overview) for page visits, search queries, AI chat insights, and user journeys. | Feature | Fern Docs | Stainless Docs | |---------|-----------|----------------|