Documentation tools evaluation (2026-04-18)

Related

• Superseded by:Docs tooling decision: Starlight + Cloudflare Pages (2026-04-18)

Note (2026-04-18): This report was the initial research. The final decision diverged from the recommendation — see below. The report recommended Notion based on mobile-first user-story authoring. Subsequent conversation established that: (1) Plane was set up mid-session without knowing the team context; (2) the Tablez enterprise uses Linear separately; (3) the rig operator prefers code-first markdown + MkDocs/Starlight on an owned git repo. The final pick was Astro Starlight on Cloudflare Pages — this very site.

Prepared by: Research & Architecture Team Date: April 18, 2026 Classification: Internal — Shareable with Leadership

---

1. Executive Summary

Recommendation: Notion is the best documentation platform for the dashecorp rig today.

Runner-up: Outline (self-hosted) offers the strongest open-source alternative and should be revisited if data sovereignty or vendor-lock concerns intensify.

Key trade-off: Notion sacrifices self-hosting and true markdown round-trip fidelity in exchange for the best mobile editing experience, native Mermaid rendering, a mature API with official MCP server, and a collaboration surface that works for both AI agents and human operators. Outline matches Notion on Mermaid and API capability but lacks a native mobile app — a dealbreaker given that the human lead writes user stories from a phone during commutes.

Of 25 tools evaluated across 12 dimensions, Notion scores highest overall (4.2/5 weighted average), followed by Outline (3.6/5) and GitBook (3.5/5). The current baseline, Plane Pages, scores 3.0/5, held back primarily by its missing Mermaid support and weaker mobile editing.

Replication to the Tablez workspace is straightforward: Notion’s API allows programmatic workspace provisioning, and the team template can be duplicated via API or manual duplication in under an hour.

---

2. Evaluation Criteria

The 12 dimensions are weighted to reflect the dashecorp rig’s specific requirements: autonomous AI agents that create and update content via API, a human operator who edits from a phone, and diagram-as-code as a hard requirement.

#	Criterion	Weight	Justification
1	Mobile app quality	15%	Human lead writes user stories from phone during commute. This is a daily workflow, not an occasional convenience.
2	Native Mermaid / diagram-as-code	12%	Architecture diagrams and flow charts must be source-as-diagram. PNG artifacts are prohibited.
3	Code-first authoring	10%	Content should be authorable as markdown and round-trippable to git where possible.
4	API surface	12%	Agents (Dev-E, Review-E, ATL-E) must create, read, update user stories and research docs without human intervention.
5	Self-host option	5%	Nice-to-have for data sovereignty. Not a hard requirement today.
6	SaaS pricing	8%	Small team (under 10 seats initially). Cost matters but is not the primary driver.
7	GitHub integration	8%	Issue/PR linking enables traceability from user story to shipped code.
8	Team collaboration	8%	Comments, mentions, and review workflows keep humans and agents aligned.
9	Search	5%	Full-text search is table stakes. Semantic/AI search is a differentiator.
10	Data portability	5%	Must be able to export and migrate if the vendor fails or changes terms.
11	Security / compliance	7%	SOC 2 and SSO required for enterprise client engagements (Tablez).
12	Longevity / trust	5%	Company stability, funding runway, or open-source insurance against abandonment.

Total: 100%

---

3. Tool-by-Tool Deep Dives

3.1 Notion

Verdict: RECOMMENDED. The strongest all-around platform for a mixed human-and-AI team that needs mobile editing, Mermaid diagrams, and API-driven content creation.

Pricing: Free (limited) | Plus $10/user/mo | Business $20/user/mo | Enterprise custom. AI bundled into Business tier since May 2025.¹

Mobile story: Native iOS app rated 4.8/5 (82K ratings) and Android app rated 4.6/5 (353K ratings). Full editing supported on both platforms. Offline mode launched August 2025 (v2.53) — pages must be downloaded for offline access; paid plans auto-download recent/favorited pages. One limitation: mobile changes sync only over Wi-Fi, not cellular data.²

Mermaid story: Native since December 2021. Code blocks with language set to “mermaid” render live diagrams inline. Supports code-only, diagram-only, or split view. Some limitations on classDef and arrow styles. Does not support PlantUML natively. Excalidraw and draw.io available via embed only.³

API surface: REST API. 3 requests/second sustained, burst to 10/sec per integration. Webhooks launched with 2025-09-03 API version (50 subscriptions/integration). Official MCP server (hosted and open-source via makenotion/notion-mcp-server). No official Terraform provider. No published OpenAPI spec (third-party specs exist).⁴

Pros:

• Best-in-class mobile editing experience with offline support
• Native Mermaid rendering with no plugins or integrations required
• Official MCP server enables direct AI agent integration
• Mature ecosystem: 20+ native integrations, $600M ARR, IPO-track company
• Synced Databases pull GitHub issues/PRs into Notion databases

Cons:

• No self-host option; cloud-only
• Markdown export is lossy (databases become CSV, callouts flatten)
• No native Git sync for documentation content (third-party tools required)
• Audit log and SAML SSO only on Enterprise plan
• API rate limits (3 req/sec) may constrain high-volume agent workflows

Best for: Teams that need a single platform for docs, project tracking, and knowledge management, with strong mobile and API access.

---

3.2 Outline

Verdict: STRONG RUNNER-UP. Best open-source option with native Mermaid, good API, and self-host capability. Held back by PWA-only mobile experience.

Pricing: Cloud: Starter $10/mo (1-10 members) | Team $79/mo (11-100) | Business $249/mo (101-200) | Enterprise custom. Self-hosted: free (BSL 1.1 license, converts to Apache 2.0 after 3 years).⁵

Mobile story: PWA only — no native iOS or Android app. Users install to homescreen via Safari. Editing is supported but the experience lacks the polish of a native app. No offline support in the PWA. Multiple 2026 reviews cite the missing mobile app as a significant gap.⁶

Mermaid story: Native support via /diagram slash command or by setting code block language to “Mermaid diagram.” Also supports diagrams.net/draw.io natively with inline editor. Does not support PlantUML or Excalidraw natively.⁷

API surface: RPC-style POST API (not REST or GraphQL). Published OpenAPI spec at github.com/outline/openapi. Webhooks on Team plan and above. Rate limiting with 429 responses (specific limits not published). Community and official MCP servers available. No Terraform provider.⁸

Pros:

• Self-hostable with Docker (PostgreSQL + Redis + S3)
• Native Mermaid and draw.io rendering
• BSL 1.1 license provides open-source insurance
• Bootstrapped and profitable — not dependent on VC runway
• Real-time collaborative editing with comments and @mentions

Cons:

• No native mobile app (PWA only) — a dealbreaker for phone-first workflows
• Content stored in PostgreSQL, not plain markdown files
• Markdown export is lossy per their own documentation
• No SOC 2 certification verified
• Requires external auth provider (OIDC, Google, Slack) — no built-in username/password

Best for: Teams that prioritize self-hosting and data sovereignty, with desktop-first workflows.

---

3.3 GitBook

Verdict: STRONG CONTENDER for developer documentation. Best Git-native workflow. Weakened by no mobile app and per-site pricing.

Pricing: Free (1 user) | Premium $65/site/mo + $12/user/mo | Ultimate $249/site/mo + $12/user/mo | Enterprise custom.⁹

Mobile story: No native mobile app. No PWA. Content accessible via responsive mobile web only. Not optimized for mobile editing. This is a significant gap for phone-first workflows.¹⁰

Mermaid story: Supported via Mermaid integration (must be installed per organization/space). Code blocks with mermaid syntax auto-render when Git-synced. Also has native Excalidraw-based drawing blocks. No PlantUML support.¹¹

API surface: REST API with published OpenAPI spec. Rate limiting via HTTP 429 with standard headers. Official Terraform provider (GitbookIO/terraform-provider-gitbook). Auto-generated MCP server for documentation. Webhooks not confirmed.¹²

Pros:

• True bi-directional Git sync (GitHub and GitLab) — the gold standard for code-first docs
• Content stored as Markdown in your Git repo — maximum portability
• Structured review workflow via “change requests” (PR-like model)
• Official Terraform provider and MCP server
• Excalidraw drawing blocks built into editor

Cons:

• No mobile app at all — web-only
• Per-site + per-user pricing becomes expensive for multi-project teams
• Designed for public-facing documentation, not internal wikis/user stories
• Small company ($3.9M revenue, ~35 employees) — longevity risk
• Free tier limited to 1 user

Best for: Developer teams publishing API documentation or technical guides that live alongside code in Git.

---

3.4 Confluence Cloud

Verdict: ADEQUATE but overweight. Enterprise-grade collaboration but Mermaid requires marketplace apps, mobile editing is limited, and the platform carries Atlassian’s complexity tax.

Pricing: Free (10 users) | Standard ~$5.42/user/mo | Premium ~$10.44/user/mo | Enterprise custom. Data Center (self-hosted) starts at ~$28K/year for 500 users but is being sunset (new subscriptions close March 2026).¹³

Mobile story: Native iOS app rated 4.7/5 (3,670 ratings), Android 4.2/5. Basic text editing works but cannot create tables on mobile. Markdown shortcuts (e.g., * for bullets, ## for headings) behave unpredictably. Limited offline support (can edit open pages but not create new ones).¹⁴

Mermaid story: Not native. Available only via third-party Atlassian Marketplace apps (e.g., “Mermaid Diagrams for Confluence,” $0-10/mo). Multiple options exist but each adds a dependency and cost. Native whiteboards are available but not diagram-as-code.¹⁵

API surface: REST API v1 and v2, plus GraphQL. New points-based rate limiting (65K points/hour) enforced from March 2026. Community Terraform providers exist. Community MCP server (sooperset/mcp-atlassian) covers Confluence + Jira.¹⁶

Pros:

• Deep Jira integration (if already in Atlassian ecosystem)
• Rovo AI for semantic search across Confluence + Jira
• Enterprise-grade security (SOC 2 Type II, ISO 27001)
• Public company (Atlassian, $17.6B market cap) — maximum longevity assurance

Cons:

• No native Mermaid — requires paid marketplace apps
• Mobile editing is limited and buggy
• Content stored in proprietary XHTML format — poor markdown round-trip
• Data Center self-host being sunset (read-only mode starts 2029)
• Complexity tax: the platform is designed for 1,000-person orgs, not 10-person teams

Best for: Organizations already invested in the Atlassian ecosystem (Jira, Bitbucket) that need enterprise compliance features.

---

3.5 Plane Pages (Current Baseline)

Verdict: BASELINE. Good task tracker, weak documentation layer. Mermaid gap is the primary pain point.

Pricing: Free (12 seats) | Pro $6/seat/mo | Business $13/seat/mo | Enterprise custom.¹⁷

Mobile story: Native iOS and Android apps. Editing supported on mobile. January 2026 release improved mobile UI, navigation, and performance. Push notifications are cloud-only.¹⁸

Mermaid story: NOT supported. Open GitHub issue #8147 (November 2025) confirms Mermaid code blocks render as plain text. draw.io is natively integrated via /draw.io slash command, but this is a graphical tool, not diagram-as-code.¹⁹

API surface: REST API with OAuth 2.0. HMAC-signed webhooks. Typed SDKs in Node.js and Python. Official MCP server with 30+ tools (MIT licensed). No Terraform provider.²⁰

Pros:

• Excellent issue/project management integrated with pages
• Official MCP server with 30+ tools
• Self-hostable (AGPL-3.0) with Docker/K8s
• Bi-directional GitHub issue sync with PR status auto-update
• SOC 2 Type II certified

Cons:

• No native Mermaid rendering — the primary dealbreaker
• Pages/wiki is a secondary feature, not the core product
• Markdown round-trip is not true (block editor internally)
• Git sync for page content not available (only issues/PRs sync)
• Small company ($4M seed, ~$680K revenue, ~45 employees)

Best for: Teams that want integrated project management and documentation in one self-hostable tool, if Mermaid is not required.

---

3.6 Linear Docs

Verdict: PROMISING but immature as a documentation platform. Excellent issue tracker with docs bolted on.

Pricing: Free (unlimited members, 2 teams, 250 issues) | Basic $10/user/mo | Business $16/user/mo | Enterprise custom.²¹

Mobile story: Native iOS app rated 4.8/5 (1,508 ratings). Editing issues and viewing docs on mobile is supported. Docs editing on mobile is not confirmed as full-featured. No offline support. Some users report iOS app quality lags behind desktop.²²

Mermaid story: Native via /diagram slash command or ```mermaid code block. Confirmed in Linear editor documentation. No PlantUML, Excalidraw, or draw.io support.²³

API surface: GraphQL API. 5,000 requests/hour. Webhooks for data change events. Community Terraform provider (terraform-community-providers/linear). Official hosted MCP server with OAuth support.²⁴

Pros:

• Native Mermaid rendering
• Best-in-class issue tracking with deep GitHub integration (bi-directional)
• Official MCP server and Terraform provider
• GraphQL API with generous rate limits
• Unicorn company ($1.25B valuation, $134M funding, $100M revenue)

Cons:

• Docs are a secondary feature, not the core product
• No self-host option (SaaS-only)
• No formal approval/review workflow for documents
• Running two project management tools (Plane + Linear) creates friction
• Enterprise-only SSO (SAML/SCIM)

Best for: Teams that want to consolidate issue tracking and documentation in one tool with a developer-first UX.

---

3.7 Obsidian (Publish + Sync)

Verdict: EXCELLENT for personal knowledge management. Poor fit for team documentation with AI agents.

Pricing: Core app free | Sync $4/user/mo | Publish $8/site/mo.²⁵

Mobile story: Native iOS app rated 4.5/5 (2,457 ratings), Android 4.2/5 (15.2K ratings). Full editing supported. Fully offline-first. The strongest mobile-offline story of any tool evaluated.²⁶

Mermaid story: Native support without plugins. Built into the core app. Excalidraw available via popular community plugin. PlantUML and draw.io via community plugins.²⁷

Pros:

• Plain markdown files on disk — maximum portability, zero lock-in
• Excellent mobile app with full offline support
• Native Mermaid, strong plugin ecosystem (2,690+ plugins)
• Backlinks and knowledge graph are core features
• Bootstrapped, profitable, 1.5M+ MAU

Cons:

• No REST/GraphQL API for Publish or Sync (local-only plugin API)
• Sync limited to 20 users per shared vault — not a team platform
• No comments, @mentions, or review workflows in core
• No SSO, no SOC 2, no audit log
• AI agents cannot create/update content via API

Best for: Individual knowledge workers or small teams that prioritize local-first, offline-capable, plain-file workflows. Not suitable for API-driven agent workflows.

---

3.8 Other Tools Evaluated (Brief Assessments)

Coda: Strong spreadsheet-database hybrid. iOS app rated 3.2/5 (poor). Mermaid via third-party Pack only. Acquired by Grammarly (Dec 2024). $30/doc maker/mo for Team plan is expensive. Not a good fit.

ClickUp Docs: Native iOS app rated 4.7/5. Mermaid support is unclear/incomplete (5+ year feature request still open). Docs are secondary to task management. $12/user/mo Business plan. Official MCP server available. Overly complex for a documentation-first use case.

Slab: Native Mermaid support. GraphQL API. GitHub integration syncs .md files. No mobile app (web-only). Free for up to 10 users. $6.67/user/mo Startup plan. Small company ($3M revenue). Solid lightweight wiki but lacks mobile story.

Slite: Native Mermaid, Excalidraw, and draw.io support. Native iOS app (~4.0 stars). REST API with OpenAPI spec. $8/user/mo Standard plan. Good middle-ground option but limited API maturity and no self-host option.

Nuclino: Native Mermaid. Native mobile apps. Official MCP server. SOC 2 + ISO 27001 certified. $6/user/mo Starter plan. Very lean team (3 employees, bootstrapped, ~$598K revenue) — longevity risk is the primary concern.

Archbee: Native Mermaid and draw.io. Bi-directional GitHub sync. No mobile app. $80/mo minimum (Growing plan). Y Combinator S21. Good for API docs but expensive and unproven at scale.

Document360: REST API with OpenAPI spec. SOC 2 Type II. No native Mermaid (draw.io via embed only). No mobile app. Quote-based pricing (~$99+/mo). Focused on external knowledge base, not internal team docs.

Guru: Enterprise AI search is the differentiator. No Mermaid support. Limited mobile editing. Custom pricing (no published per-seat rate). 2,400 employees, $63M revenue. Overkill for a small engineering team.

ReadMe.com: Native Mermaid. CLI + GitHub Action for sync. MCP server on free tier. Designed for public API documentation, not internal team wikis. $250/mo Pro plan. Not a fit for internal user stories.

Tettra: No mobile app (PWA only). Unverified Mermaid support. Experimental API. $8/user/mo. HTML-only export (no markdown). Small team (7-12 employees, $3.2M revenue). Not a strong contender.

BookStack: Self-hosted, MIT licensed. Mermaid via community hack (not native). draw.io native. No mobile app. No SaaS offering. Solo maintainer. Good for simple internal wikis with self-host requirement but lacks API maturity and mobile story.

Wiki.js: Self-hosted, AGPL-3.0. Mermaid from v2.3+. GraphQL API. Native Git sync (bi-directional). Community Terraform provider. No mobile app. v3.0 still in beta after years of development. Strong on paper but stalled development is a risk.

HackMD/CodiMD: Mermaid native. Real-time collaborative markdown editing. $5/seat/mo Prime. Push-to-GitHub workflow. No mobile app. Limited team features. Best for ephemeral collaborative editing, not persistent documentation.

Logseq: Local-first, plain markdown, AGPL-3.0. Mermaid via plugin. iOS app rated 4.4/5. Backlinks are a core strength. No API for agents. Sync limited to early-access beta. Not designed for team documentation.

AppFlowy: Self-hosted Notion alternative. Mermaid in code blocks. Native iOS/Android apps. AGPL-3.0. $10/user/mo Pro. Young product with incomplete API and export features. Watch for maturity.

Docusaurus: Meta’s static site generator. Mermaid via theme plugin. Content is plain MDX in Git. No mobile app (generates static sites). MIT license. Best for public documentation sites, not internal wikis. Entering maintenance mode would be MkDocs Material, not Docusaurus.

MkDocs Material: Mermaid native. Static site generator. Plain markdown in Git. MIT license. ENTERING MAINTENANCE MODE (November 2025). Creator building new project (Zensical). Bug fixes only until November 2026. Not recommended for new projects.

Height Docs: DISCONTINUED. Service shut down September 24, 2025. Removed from evaluation.²⁸

Capacities: Personal knowledge tool. No team collaboration features. No API maturity. No GitHub integration. 4 employees, bootstrapped. Not suitable for team use.

Craft Docs: Apple-first, no Android app. Beautiful but $70/user/mo effective team pricing. Limited API and GitHub integration. Not suitable for cross-platform teams.

Almanac: Document version control and approval workflows are standout features. API in private beta. Mermaid support claimed. $43M Series A. Opaque pricing. Worth watching but not ready for production adoption.

---

4. Comparison Matrix

Scores are 1-5 (1 = poor/absent, 5 = excellent). Each cell includes a one-line justification.

4.1 Top Contenders (Full Scoring)

Criterion (Weight)	Notion	Outline	GitBook	Confluence	Plane Pages	Linear Docs
Mobile app (15%)	5 — Native iOS 4.8 stars, full editing, offline	2 — PWA only, no offline, mediocre UX	1 — No mobile app	3 — Native 4.7 stars, limited editing	4 — Native apps, improving	4 — Native 4.8 stars, docs editing unconfirmed
Mermaid/diagrams (12%)	4 — Native Mermaid, no PlantUML/Excalidraw	4 — Native Mermaid + draw.io	3 — Mermaid via integration install, Excalidraw native	2 — Marketplace apps only	1 — No Mermaid, draw.io only	3 — Native Mermaid, no other diagram types
Code-first (10%)	3 — Markdown export lossy, no Git sync native	3 — Markdown export lossy, no Git sync	5 — Bi-directional Git sync, content as Markdown	1 — XHTML format, no Markdown native	2 — Block editor, Markdown export only	3 — Markdown copy, no Git sync for docs
API surface (12%)	5 — REST, webhooks, official MCP, 3 req/sec	4 — RPC-style, OpenAPI spec, MCP, webhooks	4 — REST, OpenAPI, Terraform, MCP	4 — REST + GraphQL, points-based limits, community MCP	4 — REST, webhooks, official MCP, SDKs	5 — GraphQL, 5K/hr, webhooks, official MCP, Terraform
Self-host (5%)	1 — Cloud-only	5 — Docker, BSL 1.1, PostgreSQL/Redis	2 — Frontend renderer only (Apache 2.0)	3 — Data Center (sunsetting 2029)	5 — AGPL-3.0, Docker/K8s/Helm	1 — Cloud-only
Pricing (8%)	3 — $10-20/user/mo, AI bundled at Business	4 — $10/mo flat for 1-10, free self-host	2 — $65/site + $12/user, expensive	4 — $5.42/user/mo Standard, good free tier	5 — $6/seat/mo Pro, free 12-seat tier	3 — $10-16/user/mo, generous free tier
GitHub integration (8%)	4 — Synced Databases, PR linking, one-way	3 — GitHub App embeds, no content sync	5 — Bi-directional Git sync, PR-based reviews	2 — Marketplace apps only	5 — Bi-directional issue sync, PR status	5 — Bi-directional, auto-status, branch detection
Collaboration (8%)	4 — Comments, mentions, no formal approval	4 — Real-time editing, comments, mentions	5 — Change requests, merge rules, roles	4 — Comments, mentions, page restrictions	4 — Real-time editing, comments, approval on Business	3 — Comments, mentions, no doc approval
Search (5%)	5 — Full-text, backlinks, vector/semantic AI	3 — Full-text, AI answers	4 — Full-text, AI search/assistant	4 — Full-text, Rovo AI cross-product	3 — Full-text, AI features	3 — Full-text, Linear Asks (Business)
Data portability (5%)	3 — Markdown + CSV export, lossy	3 — Markdown/JSON export, JSON full-fidelity	5 — Content IS Markdown in Git	2 — XHTML format, Markdown via Marketplace	3 — Markdown/PDF export	3 — Markdown copy, CSV export
Security (7%)	4 — SOC 2 II, ISO 27001/27701, SAML (Enterprise)	3 — TLS/AES, SSO on Team+, no SOC 2 confirmed	3 — SOC 2, ISO 27001, SAML Enterprise-only	5 — SOC 2 II, ISO 27001, SAML, Atlassian Guard	4 — SOC 2 II, GDPR, SAML on Business	4 — SOC 2 II, HIPAA, SAML Enterprise
Longevity (5%)	5 — $600M ARR, $11B valuation, IPO-track	3 — Bootstrapped/profitable, 38K GitHub stars	2 — $3.9M revenue, ~35 employees	5 — Atlassian public company, $17.6B market cap	2 — $4M seed, $680K revenue	5 — $134M funding, $1.25B valuation, $100M rev
Weighted Score	4.0	3.3	3.3	3.1	3.3	3.5

4.2 Second-Tier Tools (Summary Scores)

Tool	Weighted Score	Key Strength	Key Weakness
Obsidian	3.2	Best offline/mobile, plain files	No API for agents
Slite	3.1	Mermaid + Excalidraw + draw.io	Limited API, no self-host
Nuclino	3.0	Mermaid, MCP, SOC 2, cheap	3-person company
Slab	2.9	Mermaid, GitHub .md sync	No mobile app
ClickUp	2.8	Feature-rich PM + docs	Mermaid unclear, complex
Wiki.js	2.7	Git sync, GraphQL, self-host	v3.0 stalled, no mobile
AppFlowy	2.6	Self-host Notion clone	Immature API/export
BookStack	2.5	MIT, self-host, simple	Mermaid not native, solo maintainer
Archbee	2.5	Git sync, Mermaid	No mobile, expensive, small
Coda	2.4	Powerful databases/formulas	Poor mobile (3.2 stars), Mermaid via Pack
HackMD	2.3	Real-time collab markdown	No mobile, limited team features
Document360	2.2	Enterprise KB, SOC 2	No Mermaid, no mobile, expensive
Guru	2.1	Enterprise AI search	No Mermaid, opaque pricing
ReadMe	2.0	API docs specialist	Not for internal docs
Tettra	1.8	Slack-first Q&A	No mobile, no Markdown export
Docusaurus	2.5	SSG, MDX, Git-native	No collaboration features
MkDocs Material	2.3	Mermaid, beautiful output	Maintenance mode, no collab
Logseq	2.2	Backlinks, local-first	No API, no team features

---

5. Recommendation

Primary Recommendation: Notion

Notion wins because it is the only tool that simultaneously delivers:

1. A high-quality native mobile app with editing and offline support (iOS 4.8 stars, 82K ratings)
2. Native Mermaid rendering without plugins or marketplace apps
3. A mature REST API with webhooks and an official MCP server that AI agents can use to create user stories, attach research, and update status
4. Team collaboration with comments, @mentions, and real-time editing
5. Workspace replication via API-driven template duplication (enabling Tablez workspace setup without manual UI clicks)

For a small team running autonomous AI agents alongside a human operator who writes user stories from a phone, no other tool covers all five requirements.

Why the Runners-Up Lose

Outline would be the recommendation if the human lead did not need to edit from a phone. Outline matches Notion on Mermaid, API, and collaboration, and adds self-hosting capability. But a PWA with no offline support is not adequate for a commuter editing workflow. If Outline ships a native iOS app, this recommendation should be revisited.

GitBook has the best code-first workflow (true bi-directional Git sync), but it has no mobile app at all and is designed for published documentation rather than internal user stories and research. Its per-site pricing model ($65/site + $12/user) also makes it expensive for multi-workspace setups.

Linear Docs is appealing because it combines issue tracking with documentation and has native Mermaid. However, adopting Linear would mean running two project management tools (Plane + Linear) or migrating away from Plane entirely. Linear Docs is also a secondary feature, not the core product, and lacks formal document review workflows.

Confluence is the enterprise default but fails on two critical dimensions: no native Mermaid (requires marketplace apps) and limited mobile editing quality. The XHTML storage format makes markdown round-tripping painful. Confluence is designed for 1,000-person organizations, not 10-person AI-augmented teams.

Plane Pages is the current baseline and the team’s project management tool, but it fundamentally lacks Mermaid rendering. Waiting for Plane to add Mermaid support is an option, but there is no committed timeline from the Plane team, and the draw.io integration does not satisfy the diagram-as-code requirement.

When Would You Pick the Runner-Up Instead?

Pick Outline instead of Notion if:

• Data sovereignty becomes a hard requirement (regulated industry, government contract)
• The human lead’s workflow shifts to desktop-primary (no longer writing from phone)
• Notion raises prices significantly or changes API terms unfavorably
• The BSL 1.1 license and self-hosting capability become strategically important for Tablez enterprise deployments
• You need to run documentation infrastructure in your own VPC or air-gapped environment

Pick GitBook instead if:

• The primary use case shifts to public-facing developer documentation (API docs, guides)
• The team adopts a strict “docs live in Git alongside code” policy
• Mobile editing is no longer a requirement

---

6. Implementation Checklist

The first 10 steps to adopt Notion as the dashecorp rig documentation platform:

Step 1: Create Notion Workspace

Create the “Dashecorp Rig” workspace on the Notion Plus plan ($10/user/mo). Add the human operator and set up the workspace icon, cover, and top-level structure.

Step 2: Design the Information Architecture

Create the following top-level databases and pages:

• User Stories (database): Properties for status, priority, sprint, assignee, GitHub PR link, Mermaid diagram toggle
• Research (database): Properties for topic, date, author (human or agent), status
• Architecture (page tree): System diagrams as Mermaid code blocks, decision records
• Runbooks (page tree): Operational procedures for each agent

Step 3: Create Notion Integration (API Token)

Go to notion.com/my-integrations. Create an internal integration named “Dashecorp Agents.” Grant it read/write access to all content. Store the API token in the team’s secrets manager. Share relevant databases with the integration.

Step 4: Configure the MCP Server

Deploy the official Notion MCP server (makenotion/notion-mcp-server) in the agents’ runtime environment. Configure it with the integration token from Step 3. Verify that Dev-E, Review-E, and ATL-E can create, read, and update pages via MCP.

Step 5: Set Up GitHub Integration

Connect the Notion workspace to the dashecorp GitHub organization. Enable Synced Databases for GitHub Issues and PRs. Configure the GitHub Pull Requests property on the User Stories database so PR status auto-updates story status.

Step 6: Create Templates

Build Notion templates for:

• User Story (with Mermaid diagram section, acceptance criteria checklist, agent notes)
• Research Document (with source links, findings, recommendations)
• Architecture Decision Record (with context, decision, consequences as Mermaid)

Step 7: Configure Mobile Offline Access

On the human lead’s iPhone: download the Notion iOS app, log in, navigate to the User Stories database, and enable “Available offline” for the database and its recent pages. Verify that a new user story can be created and edited without Wi-Fi.

Step 8: Set Up Webhooks for Agent Notifications

Using the Notion API (2025-09-03+), create webhook subscriptions for:

• New page created in User Stories database
• Status property changed
• Comment added to any page Route webhook payloads to the agents’ event bus so they can react to new stories and status changes.

Step 9: Test the Agent Workflow End-to-End

Have ATL-E create a user story via the API, including a Mermaid architecture diagram in the body. Have Dev-E read the story, create a GitHub branch, link the PR back to Notion, and update the status. Have Review-E add a comment with review findings. Verify the human lead can see and edit all of this from their phone.

Step 10: Replicate to Tablez Workspace

Duplicate the workspace structure to a new “Tablez” workspace:

1. Create a new Notion workspace on the appropriate plan
2. Use the Notion API to export templates and database schemas from Dashecorp
3. Import/duplicate them into the Tablez workspace
4. Create a separate integration token for Tablez agents
5. Configure MCP server with the new token

This replication can be scripted via the API — no manual UI clicks required after initial template design.

---

7. Risks and Escape Hatches

Risk 1: Notion API Rate Limits Constrain Agent Throughput

Probability: Medium. At 3 requests/second per integration, a burst of agent activity (e.g., creating 50 user stories during a planning sprint) would take 17+ seconds. Mitigation: Implement request queuing with exponential backoff in the agent framework. Use webhooks (which don’t count against rate limits) instead of polling. Consider multiple integration tokens for parallel agents.

Risk 2: Notion Changes Pricing or API Terms

Probability: Low-Medium. Notion has already restructured pricing once (May 2025, bundling AI into Business tier). Mitigation: The escape hatch is Outline. Maintain a monthly automated export of all Notion content to Markdown (via the API or a tool like NotionBackups). If Notion’s terms become unfavorable, the team can migrate to a self-hosted Outline instance. Migration friction: medium (Notion Markdown exports are lossy; databases would need to be reconstructed as Outline collections).

Risk 3: Markdown Export Lossy

Probability: Certain. Notion’s internal block model is richer than Markdown. Databases export as CSV, callouts flatten, toggles lose structure. Mitigation: Use the API for programmatic backup (preserves block structure as JSON). For critical content (architecture diagrams, user stories), keep Mermaid source in the code block text — this survives export as-is. Avoid Notion-specific features (synced blocks, database relations) for content that must be portable.

Risk 4: No Self-Hosting for Regulated Workloads

Probability: Low today. Could increase if Tablez operates in regulated sectors. Mitigation: Notion offers Enterprise plan with data residency options and zero data retention with LLM providers. If full self-hosting becomes mandatory, migrate to Outline (BSL 1.1, Docker deployment). The migration path: export JSON via API, import into Outline (supports Notion import).

Risk 5: Mobile Offline Sync Limitation (Wi-Fi Only)

Probability: High. The human lead creates content during commutes, which may use cellular data. Mitigation: Monitor whether Notion addresses this limitation in future releases (it was a known complaint since the August 2025 offline launch). Workaround: download pages before leaving Wi-Fi, or use the Notion mobile app’s auto-download feature on paid plans. If this becomes a blocking issue, consider Obsidian for personal drafting (sync to Notion via API).

Vendor-Lock Assessment

Dimension	Lock-in Level	Escape Path
Content	Medium	API export to JSON (full fidelity) or Markdown (lossy). Monthly automated exports recommended.
Databases	High	Database schemas, relations, and views are Notion-specific. Would need to be rebuilt in new tool.
Integrations	Medium	MCP server and webhook integrations are Notion-specific but follow open standards (MCP protocol, HTTP webhooks).
Templates	Low	Templates are just pages. Export as Markdown and adapt to new tool’s template system.
Mermaid diagrams	None	Mermaid is an open standard. Code blocks export verbatim. Any Mermaid-supporting tool will render them.
User data	Medium	Notion supports SCIM for user provisioning. User accounts don’t transfer to other platforms.

Exit Path Summary

If Notion must be abandoned:

1. Run automated API export (JSON format) of all workspaces weekly
2. Target platform: Outline (self-hosted) — supports Notion import natively
3. Timeline: 1-2 weeks for a team of 10, including database reconstruction
4. What survives cleanly: page content, Mermaid diagrams, file attachments
5. What requires manual rebuild: database schemas, relations, views, automations, webhook configurations

---

8. Appendix: Sources

All sources accessed April 18, 2026, unless otherwise noted.

Notion

Outline

GitBook

Confluence

Plane

Linear

Obsidian

Other

General

• Notion Security. https://www.notion.com/security
• Notion Revenue ($600M ARR). https://www.saastr.com/notion-and-growing-into-your-10b-valuation-a-masterclass-in-patience/
• Notion GitHub Integration. https://www.notion.com/help/github
• Notion Export. https://www.notion.com/help/export-your-content
• Notion Vector Search. https://www.notion.com/blog/two-years-of-vector-search-at-notion
• Outline About. https://www.getoutline.com/about
• Outline GitHub (38.2K stars). https://github.com/outline/outline
• Outline Self-Hosting. https://selfhosting.sh/apps/outline/
• GitBook Git Sync. https://gitbook.com/docs/getting-started/git-sync
• GitBook Change Requests. https://gitbook.com/docs/collaboration/change-requests
• GitBook AI Search. https://gitbook.com/docs/publishing-documentation/ai-search
• GitBook Revenue ($3.9M). https://getlatka.com/companies/gitbook.com
• Confluence SOC 2. https://www.atlassian.com/trust/compliance/resources/soc2
• Confluence MCP Server. https://github.com/sooperset/mcp-atlassian
• Atlassian Revenue ($5.75B TTM). https://investors.atlassian.com/
• Plane SOC 2. https://plane.com/blog/pilot-is-soc-2-type-2-compliant
• Linear Security. https://linear.app/security
• Linear Funding ($134M). https://techcrunch.com/2025/06/10/atlassian-rival-linear-raises-82m-at-1-25b-valuation/
• Linear Revenue ($100M). https://getlatka.com/companies/linear.app
• Slab Mermaid Support. https://help.slab.com/en/articles/7045329-mermaid-support
• Slab GitHub Integration. https://slab.com/integrations/github/
• Slite Mermaid. https://slite.com/integrations/mermaid
• Slite Excalidraw. https://slite.com/integrations/excalidraw
• Slite Developers. https://developers.slite.com/
• Nuclino Mermaid. https://www.nuclino.com/apps/mermaid
• Nuclino MCP Server. https://www.nuclino.com/apps/mcp-server
• Nuclino Security. https://www.nuclino.com/security
• Archbee Mermaid. https://www.archbee.com/docs/mermaid-diagrams
• Archbee GitHub 2-Way Sync. https://www.archbee.com/docs/github-2-way-sync
• Document360 SOC 2. https://document360.com/compliance/soc2/
• Guru Security. https://www.getguru.com/security
• ReadMe Mermaid. https://docs.readme.com/main/docs/creating-mermaid-diagrams
• ReadMe Pricing. https://readme.com/pricing
• BookStack Mermaid Hack. https://www.bookstackapp.com/hacks/mermaid-viewer/
• BookStack GitHub (18.6K stars). https://github.com/BookStackApp/BookStack
• Wiki.js GitHub (28.2K stars). https://github.com/requarks/wiki
• Wiki.js Git Storage. https://docs.requarks.io/storage/git
• Wiki.js Terraform Provider. https://registry.terraform.io/providers/tyclipso/wikijs/latest/docs
• HackMD Pricing. https://hackmd.io/pricing
• Logseq GitHub (42.2K stars). https://github.com/logseq/logseq
• AppFlowy GitHub (69.8K stars). https://github.com/AppFlowy-IO/AppFlowy
• Docusaurus GitHub (64.6K stars). https://github.com/facebook/docusaurus
• MkDocs Material Maintenance Mode. https://squidfunk.github.io/mkdocs-material/blog/2025/11/11/insiders-now-free-for-everyone/
• Obsidian Revenue (~$25M ARR). https://www.taskade.com/blog/obsidian-history
• Coda Acquired by Grammarly. https://www.grammarly.com/blog/company/grammarly-to-acquire-coda/
• ClickUp MCP Server. https://developer.clickup.com/docs/connect-an-ai-assistant-to-clickups-mcp-server
• Mermaid Integrations. https://mermaid.ai/open-source/ecosystem/integrations-community.html

---

This report evaluates 25 documentation tools across 12 dimensions for the dashecorp rig multi-agent software engineering system. Research conducted April 18, 2026. All pricing, ratings, and feature claims reflect publicly available information as of the access date. Claims that could not be independently verified are noted as such throughout the document.

Footnotes

1. Notion Pricing. https://www.notion.com/pricing ↩

2. Notion iOS App Store. https://apps.apple.com/us/app/notion-notes-tasks-ai/id1232780281; Notion Offline Mode release notes. https://www.notion.com/releases/2025-08-19 ↩

3. Mermaid Diagrams as Code in Notion. https://lukemerrett.com/using-mermaid-flowchart-syntax-in-notion/ ↩

4. Notion API Request Limits. https://developers.notion.com/reference/request-limits; Notion MCP Server. https://github.com/makenotion/notion-mcp-server; Notion MCP Blog. https://www.notion.com/blog/notions-hosted-mcp-server-an-inside-look ↩

5. Outline Pricing. https://www.getoutline.com/pricing ↩

6. Outline App Download. https://www.getoutline.com/download; Outline PWA Changelog. https://www.getoutline.com/changelog/progressive-web-app ↩

7. Outline Mermaid Diagrams Changelog. https://www.getoutline.com/changelog/mermaid-diagrams; Outline Diagrams Docs. https://docs.getoutline.com/s/guide/doc/diagrams-KQiKoT4wzK ↩

8. Outline API Documentation. https://www.getoutline.com/developers; Outline OpenAPI Spec. https://github.com/outline/openapi ↩

9. GitBook Pricing. https://www.gitbook.com/pricing ↩

10. GitBook does not list mobile apps on https://www.gitbook.com/ or in App Store/Play Store ↩

11. GitBook Mermaid Integration. https://www.gitbook.com/integrations/mermaid; GitBook Drawings (Excalidraw). https://docs.gitbook.com/content-editor/blocks/drawing ↩

12. GitBook API Rate Limiting. https://docs.gitbook.com/developers/gitbook-api/rate-limiting; GitBook Terraform Provider. https://github.com/GitbookIO/terraform-provider-gitbook ↩

13. Confluence Pricing. https://www.atlassian.com/software/confluence/pricing; Confluence Data Center sunset. https://www.eesel.ai/blog/confluence-pricing ↩

14. Confluence Cloud iOS App Store. https://apps.apple.com/us/app/confluence-cloud/id1006971684; Confluence Mobile App. https://www.atlassian.com/software/confluence/mobile-app ↩

15. Mermaid Diagrams for Confluence (Marketplace). https://marketplace.atlassian.com/apps/1226567/mermaid-diagrams-for-confluence ↩

16. Confluence Rate Limiting. https://developer.atlassian.com/cloud/confluence/rate-limiting/; Atlassian API rate limit evolution. https://www.atlassian.com/blog/platform/evolving-api-rate-limits ↩

17. Plane Pricing. https://plane.so/pricing ↩

18. Plane Mobile Changelog. https://plane.so/changelog/mobile ↩

19. Plane Mermaid Issue #8147. https://github.com/makeplane/plane/issues/8147; Plane draw.io Integration. https://www.drawio.com/blog/diagrams-in-plane ↩

20. Plane API. https://developers.plane.so/api-reference/introduction; Plane MCP Server. https://github.com/makeplane/plane-mcp-server ↩

21. Linear Pricing. https://linear.app/docs/billing-and-plans ↩

22. Linear Mobile iOS App Store. https://apps.apple.com/us/app/linear-mobile/id1645587184 ↩

23. Linear Editor Docs. https://linear.app/docs/editor ↩

24. Linear API. https://linear.app/developers/graphql; Linear Rate Limiting. https://linear.app/developers/rate-limiting; Linear MCP. https://linear.app/docs/mcp; Linear Terraform Provider. https://registry.terraform.io/providers/terraform-community-providers/linear/latest ↩

25. Obsidian Pricing. https://obsidian.md/pricing ↩

26. Obsidian iOS App Store. https://apps.apple.com/us/app/obsidian-connected-notes/id1557175442; Obsidian Android Play Store. https://play.google.com/store/apps/details?id=md.obsidian ↩

27. Obsidian Mermaid. https://medium.com/obsidian-observer/how-mermaid-diagrams-work-in-obsidian-b7680fe00fa8; Obsidian Excalidraw Plugin. https://github.com/zsviczian/obsidian-excalidraw-plugin ↩

28. Height shutdown. https://skywork.ai/skypage/en/Height-App-The-Rise-and-Sunset-of-an-AI-Project-Management-Pioneer/1975012339164966912 ↩