docs: restructure the docs entrypoint around user intent#1465
Merged
Conversation
Lead with "privacy-first, open-source alternative to Claude Cowork" and cut the coding-agent framing. Reorganize the page into three scannable sections (Start / For teams / For developers), keep the existing self-host/orchestrator steps under a dedicated section below.
Rename tabs "Cloud docs" → "Cloud" and "Cloud API" → "API" for shorter, clearer labels. Replace the generic "Desktop App" and "Tutorials" groups in Start here with two outcome-based clusters: "Connect your stack" (providers, MCPs, search) and "Do work with it" (browser, automations, skills, sharing). Reorganize the flat Cloud list into three clusters that map to real admin questions: "Share with your team" (templates, skill hubs, providers), "Run in the cloud" (shared workspaces, Slack), and "Manage access" (members & RBAC). Enterprise stays at the tail as a standalone contact-sales page. Slack moves from Start here to Cloud "Run in the cloud" since the Slack setup doc itself recommends pairing Slack with a remote workspace.
Add a one-liner in the developers section pointing to the changelog and roadmap, and include both in the footer links. Developers evaluating the project want to see shipping velocity and direction.
…psells Extract the openwork-orchestrator install steps out of the intro into a dedicated Self-host page. Keeps the intro short and gives self-hosters a direct, linkable entry point. The page includes two upsell paths: - Cloud, for readers who realize mid-read they don't want to run infra. Links into the team primitives (skill hubs, providers, RBAC, shared workspaces) that are hardest to replicate on your own box. - Enterprise, framed around concrete scale pressures (SSO, audit, allowlists, VPC, support) rather than a generic 'talk to sales' pitch. Links to the existing cloud-enterprise contact page. Add the page to the Start here tab as a top-level sibling of the intro so self-hosters find it immediately.
Self-hosting is what people reach for after they've installed the desktop app and tried the basic flow, not before. Move it below "Connect your stack" and "Do work with it" so the sidebar reflects that progression.
"OpenWork" as a sidebar label is tautological — every page is about OpenWork. "Introduction" tells the reader what the page is, which is what a sidebar label is for. The in-page hero copy still carries the positioning.
Sidebar labels should describe what the reader wants to do, not what the page is. Rename every page title to start with (or imply) a verb: - Introduction → Get started - How to connect ChatGPT to Openwork → Connect ChatGPT - How to get an Anthropic API key → Connect Anthropic - Adding a custom LLM provider/model → Connect a custom LLM - Adding a custom MCP → Add an MCP server - Enable Advanced Search with Exa → Enable Exa search - Controlling your browser with OpenWork → Control the browser - Automating Tasks → Automate tasks - Importing a skill → Import a skill - How to share your agents with others → Share your setup - Self-host OpenWork → Self-host - Missing Documentation? → Report missing docs Makes the sidebar scannable by intent: each label is a thing the reader is trying to accomplish.
"Connect X" flattened two different setup flows into one label. Readers scanning the sidebar need to know what they'll do before clicking: - Sign in with ChatGPT (OAuth, no key needed) - Add Anthropic API key (paste a secret from Anthropic) - Add a custom LLM (config, not auth) MCP and Exa labels already carry their own distinct verbs and are left unchanged.
"Missing docs?" as a question invites the click. Inside, offer both the low-effort path (email us) and the contributor path (open a PR against the docs folder). Drops the "A message from the Openwork Developers" preamble, which was noise.
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
The following comment was made by an LLM, it may be inaccurate: |
Mirrors the tab/group structure in docs.json so files are easier to locate. Filenames now track page titles (prefixes like how-to- and cloud- dropped since folders provide that context). Single-page groups stay flat at the tab root; roadmap and changelog remain at repo root as their own tabs. Cross-links in mdx files and docs.json redirects updated for the new paths.
…assets Moves roadmap.mdx and changelog.mdx into their own tab folders for consistency with the rest of the reorg, and removes the orphaned introduction.mdx. Renames CleanShot/Screenshot/image-* files to descriptive names based on content and updates the corresponding alt text. Unused images and a stray .mov land in images/deprecated/ rather than being deleted. docs.json gains /roadmap and /changelog redirects so old inbound URLs still resolve.
benjaminshafii
pushed a commit
that referenced
this pull request
May 15, 2026
* docs: rewrite intro with privacy-first positioning Lead with "privacy-first, open-source alternative to Claude Cowork" and cut the coding-agent framing. Reorganize the page into three scannable sections (Start / For teams / For developers), keep the existing self-host/orchestrator steps under a dedicated section below. * docs: regroup sidebar into outcome-based clusters Rename tabs "Cloud docs" → "Cloud" and "Cloud API" → "API" for shorter, clearer labels. Replace the generic "Desktop App" and "Tutorials" groups in Start here with two outcome-based clusters: "Connect your stack" (providers, MCPs, search) and "Do work with it" (browser, automations, skills, sharing). Reorganize the flat Cloud list into three clusters that map to real admin questions: "Share with your team" (templates, skill hubs, providers), "Run in the cloud" (shared workspaces, Slack), and "Manage access" (members & RBAC). Enterprise stays at the tail as a standalone contact-sales page. Slack moves from Start here to Cloud "Run in the cloud" since the Slack setup doc itself recommends pairing Slack with a remote workspace. * docs: surface changelog and roadmap on the intro Add a one-liner in the developers section pointing to the changelog and roadmap, and include both in the footer links. Developers evaluating the project want to see shipping velocity and direction. * docs(self-host): add dedicated self-host page with cloud/enterprise upsells Extract the openwork-orchestrator install steps out of the intro into a dedicated Self-host page. Keeps the intro short and gives self-hosters a direct, linkable entry point. The page includes two upsell paths: - Cloud, for readers who realize mid-read they don't want to run infra. Links into the team primitives (skill hubs, providers, RBAC, shared workspaces) that are hardest to replicate on your own box. - Enterprise, framed around concrete scale pressures (SSO, audit, allowlists, VPC, support) rather than a generic 'talk to sales' pitch. Links to the existing cloud-enterprise contact page. Add the page to the Start here tab as a top-level sibling of the intro so self-hosters find it immediately. * docs: move self-host below the outcome clusters Self-hosting is what people reach for after they've installed the desktop app and tried the basic flow, not before. Move it below "Connect your stack" and "Do work with it" so the sidebar reflects that progression. * docs: rename intro page title to "Introduction" "OpenWork" as a sidebar label is tautological — every page is about OpenWork. "Introduction" tells the reader what the page is, which is what a sidebar label is for. The in-page hero copy still carries the positioning. * docs: rewrite page titles as actions Sidebar labels should describe what the reader wants to do, not what the page is. Rename every page title to start with (or imply) a verb: - Introduction → Get started - How to connect ChatGPT to Openwork → Connect ChatGPT - How to get an Anthropic API key → Connect Anthropic - Adding a custom LLM provider/model → Connect a custom LLM - Adding a custom MCP → Add an MCP server - Enable Advanced Search with Exa → Enable Exa search - Controlling your browser with OpenWork → Control the browser - Automating Tasks → Automate tasks - Importing a skill → Import a skill - How to share your agents with others → Share your setup - Self-host OpenWork → Self-host - Missing Documentation? → Report missing docs Makes the sidebar scannable by intent: each label is a thing the reader is trying to accomplish. * docs: restore precision in provider titles "Connect X" flattened two different setup flows into one label. Readers scanning the sidebar need to know what they'll do before clicking: - Sign in with ChatGPT (OAuth, no key needed) - Add Anthropic API key (paste a secret from Anthropic) - Add a custom LLM (config, not auth) MCP and Exa labels already carry their own distinct verbs and are left unchanged. * docs: turn missing-docs into a question with two paths "Missing docs?" as a question invites the click. Inside, offer both the low-effort path (email us) and the contributor path (open a PR against the docs folder). Drops the "A message from the Openwork Developers" preamble, which was noise. * docs: reorganize into tab folders, rename files to match titles Mirrors the tab/group structure in docs.json so files are easier to locate. Filenames now track page titles (prefixes like how-to- and cloud- dropped since folders provide that context). Single-page groups stay flat at the tab root; roadmap and changelog remain at repo root as their own tabs. Cross-links in mdx files and docs.json redirects updated for the new paths. * docs: add roadmap/changelog folders, rename images, deprecate unused assets Moves roadmap.mdx and changelog.mdx into their own tab folders for consistency with the rest of the reorg, and removes the orphaned introduction.mdx. Renames CleanShot/Screenshot/image-* files to descriptive names based on content and updates the corresponding alt text. Unused images and a stray .mov land in images/deprecated/ rather than being deleted. docs.json gains /roadmap and /changelog redirects so old inbound URLs still resolve. * more clear get starter docs * docs: render get-started paths as Mintlify cards * no need to have the same title twice * edits * more concise
benjaminshafii
pushed a commit
that referenced
this pull request
May 15, 2026
* docs: rewrite intro with privacy-first positioning Lead with "privacy-first, open-source alternative to Claude Cowork" and cut the coding-agent framing. Reorganize the page into three scannable sections (Start / For teams / For developers), keep the existing self-host/orchestrator steps under a dedicated section below. * docs: regroup sidebar into outcome-based clusters Rename tabs "Cloud docs" → "Cloud" and "Cloud API" → "API" for shorter, clearer labels. Replace the generic "Desktop App" and "Tutorials" groups in Start here with two outcome-based clusters: "Connect your stack" (providers, MCPs, search) and "Do work with it" (browser, automations, skills, sharing). Reorganize the flat Cloud list into three clusters that map to real admin questions: "Share with your team" (templates, skill hubs, providers), "Run in the cloud" (shared workspaces, Slack), and "Manage access" (members & RBAC). Enterprise stays at the tail as a standalone contact-sales page. Slack moves from Start here to Cloud "Run in the cloud" since the Slack setup doc itself recommends pairing Slack with a remote workspace. * docs: surface changelog and roadmap on the intro Add a one-liner in the developers section pointing to the changelog and roadmap, and include both in the footer links. Developers evaluating the project want to see shipping velocity and direction. * docs(self-host): add dedicated self-host page with cloud/enterprise upsells Extract the openwork-orchestrator install steps out of the intro into a dedicated Self-host page. Keeps the intro short and gives self-hosters a direct, linkable entry point. The page includes two upsell paths: - Cloud, for readers who realize mid-read they don't want to run infra. Links into the team primitives (skill hubs, providers, RBAC, shared workspaces) that are hardest to replicate on your own box. - Enterprise, framed around concrete scale pressures (SSO, audit, allowlists, VPC, support) rather than a generic 'talk to sales' pitch. Links to the existing cloud-enterprise contact page. Add the page to the Start here tab as a top-level sibling of the intro so self-hosters find it immediately. * docs: move self-host below the outcome clusters Self-hosting is what people reach for after they've installed the desktop app and tried the basic flow, not before. Move it below "Connect your stack" and "Do work with it" so the sidebar reflects that progression. * docs: rename intro page title to "Introduction" "OpenWork" as a sidebar label is tautological — every page is about OpenWork. "Introduction" tells the reader what the page is, which is what a sidebar label is for. The in-page hero copy still carries the positioning. * docs: rewrite page titles as actions Sidebar labels should describe what the reader wants to do, not what the page is. Rename every page title to start with (or imply) a verb: - Introduction → Get started - How to connect ChatGPT to Openwork → Connect ChatGPT - How to get an Anthropic API key → Connect Anthropic - Adding a custom LLM provider/model → Connect a custom LLM - Adding a custom MCP → Add an MCP server - Enable Advanced Search with Exa → Enable Exa search - Controlling your browser with OpenWork → Control the browser - Automating Tasks → Automate tasks - Importing a skill → Import a skill - How to share your agents with others → Share your setup - Self-host OpenWork → Self-host - Missing Documentation? → Report missing docs Makes the sidebar scannable by intent: each label is a thing the reader is trying to accomplish. * docs: restore precision in provider titles "Connect X" flattened two different setup flows into one label. Readers scanning the sidebar need to know what they'll do before clicking: - Sign in with ChatGPT (OAuth, no key needed) - Add Anthropic API key (paste a secret from Anthropic) - Add a custom LLM (config, not auth) MCP and Exa labels already carry their own distinct verbs and are left unchanged. * docs: turn missing-docs into a question with two paths "Missing docs?" as a question invites the click. Inside, offer both the low-effort path (email us) and the contributor path (open a PR against the docs folder). Drops the "A message from the Openwork Developers" preamble, which was noise. * docs: reorganize into tab folders, rename files to match titles Mirrors the tab/group structure in docs.json so files are easier to locate. Filenames now track page titles (prefixes like how-to- and cloud- dropped since folders provide that context). Single-page groups stay flat at the tab root; roadmap and changelog remain at repo root as their own tabs. Cross-links in mdx files and docs.json redirects updated for the new paths. * docs: add roadmap/changelog folders, rename images, deprecate unused assets Moves roadmap.mdx and changelog.mdx into their own tab folders for consistency with the rest of the reorg, and removes the orphaned introduction.mdx. Renames CleanShot/Screenshot/image-* files to descriptive names based on content and updates the corresponding alt text. Unused images and a stray .mov land in images/deprecated/ rather than being deleted. docs.json gains /roadmap and /changelog redirects so old inbound URLs still resolve. * more clear get starter docs * docs: render get-started paths as Mintlify cards * no need to have the same title twice * edits * more concise
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rework the docs entrypoint so first-time visitors can pick a path and scan for actions fast. The tree gets reorganized around what readers are trying to do, not what each page is.
What changed
New positioning on the intro
Sidebar regrouped into outcome-based clusters
Before: flat list under "Desktop App" + a junk-drawer "Tutorials" group.
After:
Cloud tab also regrouped:
Tabs renamed
Cloud docs→CloudCloud API→APIPage titles rewritten as actions
Every sidebar label is now a verb phrase describing what the reader wants to do. Where the setup mechanism matters (OAuth vs API key vs config), the label reflects it — "Sign in with ChatGPT" vs "Add Anthropic API key" vs "Add a custom LLM".
New Self-host page
Carved the
openwork-orchestratorCLI steps out of the intro into a dedicated/self-hostpage. Sits below the outcome clusters — it's what people reach for after trying the desktop app. Ends with two upsell paths:Missing docs is now a question
Missing docs?invites interaction. Page offers two paths: email us, or open a PR yourself.Files touched
packages/docs/self-host.mdxpackages/docs/docs.json(tab + group restructure)packages/docs/get-started.mdx(intro rewrite + changelog/roadmap links)Start here(11 files) to action-based labelspackages/docs/missing-docs.mdx(question form + two paths)Testing
Docs-only change. Validated
docs.jsonparses as JSON. No Docker/Chrome MCP gate needed — nothing touches runtime behavior.Reviewers: worth previewing the Mintlify build locally or in a preview deployment to confirm the new groups and redirects render as expected.