From 7f15c060ae0c8c473e5bcbbf0b592063e89709c4 Mon Sep 17 00:00:00 2001 From: DeweyMarco Date: Mon, 24 Aug 2026 12:24:28 -0700 Subject: [PATCH 1/4] Add hidden POC onboarding page Adds poc-onboarding.mdx, a self-serve setup guide for enterprise customers running a Mintlify proof of concept. Covers account and repository setup, inviting the team, migrating sample content, publishing a first change, branding, the AI assistant, SSO and security, and a results review. Written for non-technical readers, with each step naming who from their team is needed and for how long. The page is not listed in docs.json and carries noindex: true, so it is reachable by direct URL only. This matches enterprise-contracting and migration-services/go-live-checklist. Co-Authored-By: Claude Opus 5 (1M context) --- poc-onboarding.mdx | 328 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 328 insertions(+) create mode 100644 poc-onboarding.mdx diff --git a/poc-onboarding.mdx b/poc-onboarding.mdx new file mode 100644 index 000000000..274492c2a --- /dev/null +++ b/poc-onboarding.mdx @@ -0,0 +1,328 @@ +--- +title: "Proof of concept onboarding" +description: "Set up a Mintlify proof of concept step by step: create your account, connect your repository, migrate sample content, enable the AI assistant, and evaluate the results." +keywords: ["POC", "proof of concept", "trial", "evaluation", "enterprise onboarding", "pilot"] +noindex: true +--- + +This guide takes you from nothing to a working Mintlify documentation site that your team can evaluate. Follow the steps in order. Each one tells you what to do, who you need from your team, and how long it takes. + +You do not need to be a developer to finish this guide. Two steps need someone with GitHub or IT access for a short time. You can do everything else yourself in a browser. + + + You have a dedicated Mintlify contact for the duration of your proof of concept (POC). If a step doesn't match what you see on screen, or you get stuck for more than a few minutes, message your shared Slack channel or email [support@mintlify.com](mailto:support@mintlify.com) instead of working around it. + + +## What you'll have at the end + + + + A real site at your own URL, running a representative sample of your content. + + + + Your team editing and publishing pages, with review before anything goes live. + + + + An assistant answering questions from your documentation, with analytics on what people asked. + + + + Single sign-on, access controls, and audit logging configured or confirmed. + + + +## Before you begin + +### People you'll need + +Line these people up before you start. Nothing here needs full-time involvement, but a missing GitHub administrator can stall the POC for days. + +| Who | What they do | When | Time needed | +|---|---|---|---| +| Documentation owner | Runs the POC and completes most steps. This is probably you. | Throughout | A few hours total | +| GitHub administrator | Approves the Mintlify GitHub App on your repository. | Step 1 | 15 minutes, once | +| Designer or brand owner | Supplies logo files, color codes, and fonts. | Step 5 | 30 minutes, once | +| Identity or IT administrator | Configures single sign-on and DNS records. | Step 7 | 1 to 2 hours, optional | +| Decision maker | Reviews the finished POC against your success criteria. | Step 8 | 1 hour | + +### What to gather + +Collect these before step 3 so you aren't waiting on other teams mid-setup: + +- Logo files for light and dark backgrounds, in SVG or PNG. +- A favicon, in SVG or PNG. +- Your brand color codes, as hex values. +- Font files, or the names of the Google Fonts you use. +- A link to your current documentation site, or an export of its content. +- Your OpenAPI specification file or URL, if you document an API. +- A list of the pages you want in the POC. See [Choose your sample content](#choose-your-sample-content) for how to pick them. + +### Decide what success looks like + +Write down three to five criteria before you start, and share them with your Mintlify contact. Without them, the review in step 8 turns into an opinion contest. + +Criteria that work well: + +- A writer with no Git experience publishes a page change without help. +- Our most complex API reference page renders correctly. +- The assistant answers 8 of our 10 most common support questions correctly. +- Our identity provider handles dashboard login. +- A documentation update goes from draft to live in under an hour. + +## Step 1: Create your account and connect your repository + +Mintlify stores every page as a file in a Git repository, and publishes your site whenever that repository changes. You connect the repository once, at the start, and then mostly forget it exists. + + + Your GitHub administrator needs organization ownership or administrator permissions on the repository to approve the Mintlify GitHub App. Ask them to be available before you begin this step. Without the app installed, your site will not deploy. + + + + + Go to [mintlify.com/start](https://mintlify.com/start) and create an account with your work email address. Use the email address you'd use for your real documentation, not a personal one, so that it maps to your identity provider later. + + + + During onboarding, connect your GitHub account, then create a new repository or select an existing empty one. A repository named `docs` inside your company's GitHub organization is a good default. A private repository is fine. + + Do not select a repository that already contains an application or other files. + + + + Your GitHub administrator installs the Mintlify GitHub App and grants it access to that one repository. Select **Only select repositories** rather than granting access to everything. + + See [Install the GitHub App](/deploy/github#install-the-github-app) for the exact permissions the app requests. Send that link to your administrator ahead of time if they want to review the permissions first. + + + Install the app anyway. GitHub sends an approval request to your organization owners, and the installation completes when they approve it. + + If that approval will take days, you can skip connecting a Git provider during onboarding. Mintlify creates a private repository for you so you can start immediately, and you can move the content to your own repository later from the [Git settings](https://app.mintlify.com/settings/deployment/git-settings) page. See [Clone to your own repository](/deploy/github#clone-to-your-own-repository). + + + + + Mintlify deploys starter content to your repository and publishes it. Your site is live at `https://.mintlify.site`. + + Find the exact URL on the **Overview** page of your [dashboard](https://app.mintlify.com/). Open it to confirm the site loads. + + + + + Use the `.mintlify.site` URL for the whole POC. It is a real, working site that you can share internally. Adding your own domain is step 7, and it is not required to evaluate anything. + + +## Step 2: Invite your team + +Add everyone who needs to see or touch the POC from the [Members](https://app.mintlify.com/settings/organization/members) page of your dashboard. + +Mintlify has three roles. Assign the narrowest one that lets each person do their job: + +- **Admin**: Changes organization settings, billing, and integrations. Give this to yourself and one backup. +- **Editor**: Creates and publishes content. Give this to your writers. +- **Viewer**: Reads the dashboard and analytics without editing. Give this to reviewers and stakeholders. + +See [Roles](/dashboard/roles) for what each role can do in detail. + +Invite people using their work email addresses. If you plan to test single sign-on in step 7, mismatched addresses mean their accounts will not link to your identity provider. + +For a useful POC, invite at least one writer who has never used Git, one engineer, and the person who will make the buying decision. The first two tell you whether the tool fits your team. The third needs to have seen it work. + +## Step 3: Get your content in + +### Choose your sample content + +Pick 20 to 50 pages. More than that slows the POC down without teaching you anything new. + +Choose the pages that are hardest to move, not the easiest: + +- Your most complex API reference page. +- A page with a large table or a deeply nested list. +- A page with images, video, or diagrams. +- A page using custom components or embedded widgets, if you have any. +- Two or three ordinary guides, so you can judge everyday quality. + +A POC built on your simplest pages tells you nothing about the migration you'd actually run. + +### Move the content + + + + Ask your Mintlify contact whether a migration is included in your POC, and what the turnaround time is. + + If it is, send them: + + - A link to your current documentation site, or an export of its content. + - The list of pages you chose. + - Your OpenAPI specification file or URL, if you have an API reference. + - Your brand assets from [What to gather](#what-to-gather). + + Mintlify ports the content, checks it, and shares a preview link so you can watch progress. See [Enterprise migrations](/migration-services/enterprise) for how the full migration process works after the POC. + + + + Mintlify has tooling for common platforms, and manual instructions for everything else: + + - [Docusaurus](/migration/docusaurus) + - [ReadMe](/migration/readme) + - [GitBook](/migration/gitbook) + - [Fern](/migration/fern) + - [Document360](/migration/document360) + - [Any other platform](/migration/manual) + + Start at [Migrate to Mintlify](/migration) to pick your path. This route needs someone comfortable running commands in a terminal. + + + +### Check the result + +Open your site and compare each sample page against the same page on your current documentation. Look for missing images, broken tables, code samples that lost their formatting, and links that go nowhere. + +Send anything wrong to your Mintlify contact in one batch rather than one message at a time. Include the page URL and what you expected to see. + +## Step 4: Publish a change yourself + +This is the step that decides most POCs. If your writers can update documentation without filing a ticket with engineering, the tool works for you. Have someone non-technical do this step, not the most technical person on your team. + + + + Go to the [web editor](https://app.mintlify.com/editor). It looks like a normal document editor and does not require any knowledge of Git. + + + + Open any page and change a sentence. See the [editor tutorial](/editor/tutorial) for a walkthrough of the interface. + + + + Select **Publish** in the top-right of the toolbar. Your change deploys automatically. + + To send changes through review instead of publishing directly, work on a branch and open a pull request. See [Branching and publishing](/editor/branching-and-publishing). + + + + Watch the deployment status on the **Overview** page of your dashboard, then refresh your site. + + + +Two things worth testing in the same step, because they change how your team works day to day: + +- **Review before publishing.** Every pull request gets its own preview URL that reviewers can open without installing anything. See [Preview deployments](/deploy/preview-deployments). +- **Updating docs from Slack.** Connect the Mintlify agent to your Slack workspace and ask it to make a change. It opens a pull request for you. See [Add the agent to Slack](/agent/slack#connect-your-slack-workspace). + +If your team writes locally in a code editor instead, they can install the [CLI](/cli/install) and preview the site on their own machine with [`mint dev`](/cli/preview). + +## Step 5: Apply your branding + +Stakeholders judge the POC partly on whether it looks like your product. This takes about 30 minutes and is worth doing before the review in step 8. + +Your site's appearance comes from a single configuration file, `docs.json`, in your repository. Set: + +- **Colors**: Your primary, light, and dark brand colors, as hex values. +- **Logo**: Separate files for light and dark mode. +- **Favicon**: The icon in the browser tab. +- **Fonts**: Google Fonts by name, or your own font files. +- **Theme**: The overall layout and style of the site. + +See [Appearance settings](/organize/settings-appearance) for every option, [Themes](/customize/themes) for the available layouts, and [Fonts](/customize/fonts) for custom typefaces. + +If editing a configuration file isn't something you want to do, send your brand assets to your Mintlify contact and ask them to apply it. + +## Step 6: Turn on the AI features + +### Enable the assistant + +Configure the assistant on the [Assistant](https://app.mintlify.com/products/assistant) page of your dashboard: + +1. Toggle the assistant on. +2. Set your support and sales [deflection emails](/assistant/configure#set-deflection-emails), so that questions the assistant can't answer route to a real person. +3. Add [sample questions](/assistant/configure#add-sample-questions) that show people what to ask. +4. Add [search domains](/assistant/configure#search-domains) if you want the assistant to draw on content outside your documentation site. + +To change the assistant's tone or teach it product-specific behavior, see [Customize the assistant](/assistant/customize) and [Assistant skills](/assistant/skills). + +### Put the assistant where your users are + +The [assistant widget](/assistant/widget) embeds the same assistant into your product dashboard, marketing site, or support portal. Adding it needs a developer for about an hour, and it is the fastest way to show your support team what deflection looks like in practice. + +### Confirm your content is ready for AI agents + +Mintlify generates these automatically. Check them, but you don't need to configure anything: + +- [`llms.txt`](/ai/llmstxt), a machine-readable index of your site. +- [`skill.md`](/ai/skillmd), a description of what agents can do with your product. This can take up to 24 hours to generate. +- An [MCP server](/ai/model-context-protocol) that lets tools like Claude and Cursor search your documentation. +- [Markdown export](/ai/markdown-export), so any page can be copied as clean text into an AI tool. + +### Test the assistant properly + +Guessing at whether the assistant is good is the most common way to waste a POC. Do this instead: + +1. Pull 20 to 30 real questions from your support tickets or community channels over the last month. +2. Ask the assistant each one. +3. Record whether the answer was correct, partly correct, or wrong. +4. For the wrong answers, check whether your documentation actually contains the answer. Usually it doesn't, and that is a content gap you now know about. + +Review what your team and your users asked on the [Assistant analytics](/analytics/assistant) page. + +## Step 7: Loop in IT and security + +Bring your IT or security team in during the POC rather than after it, so their questions don't surface during procurement. Not all of these are needed to evaluate Mintlify, so start with whichever ones appear in your success criteria. + +**Who can access your dashboard** + +- [Single sign-on](/dashboard/sso) with SAML or OIDC, including Okta, Microsoft Entra, and Google Workspace. +- [SCIM provisioning](/dashboard/scim) to create and remove accounts automatically from your identity provider. +- [Network access policies](/dashboard/network-access) to restrict dashboard access to your IP ranges. +- [Audit logs](/dashboard/audit-logs) and [session security](/dashboard/session-security). + +**Who can access your documentation site** + +If your documentation must not be public, set up [authentication](/deploy/authentication-setup). Mintlify supports password protection, OAuth, JWT, and Mintlify-managed private access. You can also [restrict individual pages to specific groups](/deploy/authentication-setup#control-access-with-groups) while leaving the rest of the site public. + +**Your domain** + +Adding a [custom domain](/customize/custom-domain) needs one DNS record from whoever manages your domain. During a POC, point a test subdomain such as `docs-preview.yourcompany.com` at the site rather than your live documentation domain. Mintlify provisions the TLS certificate automatically. + +**Analytics, checks, and compliance** + +- Connect your existing [analytics platform](/integrations/analytics/overview) so documentation traffic lands in the tools you already use. +- Enable [CI checks](/deploy/ci) to catch broken links and accessibility problems before they publish. +- For security questionnaires, certifications, and contract review, see [Enterprise contracting](/enterprise-contracting). + +## Step 8: Review the results + +Book an hour with your decision maker and walk through your criteria from [Decide what success looks like](#decide-what-success-looks-like). Use the evidence you collected rather than impressions. + +| What you're checking | Where to check it | +|---|---| +| A non-developer can publish independently | Whether step 4 worked without help, and how long it took | +| Your hardest content survived the move | Your sample pages, compared side by side with your current site | +| The assistant answers accurately | Your scored question list, plus [Assistant analytics](/analytics/assistant) | +| Readers find what they need | [Traffic](/analytics/traffic), [search](/analytics/search), and [engagement](/analytics/user-engagements) analytics | +| Readers say it's better | [Page feedback](/optimize/feedback) | +| It meets security requirements | Your IT team's sign-off from step 7 | + +Bring open questions to your Mintlify contact before the review, not during it. + +## A workable timeline + +Most POCs run two to three weeks. Compressing this into a few days is possible, but only if your GitHub administrator and brand assets are ready on day one. + +| Week | What happens | +|---|---| +| Week 1 | Steps 1 and 2: account, repository, and team. Send your content sample to be migrated, or start migrating it. Agree on success criteria. | +| Week 2 | Steps 3 to 6: review the migrated content, publish changes yourself, apply branding, and turn on the assistant. Start collecting your assistant test questions. | +| Week 3 | Steps 7 and 8: IT and security review, then the results review with your decision maker. | + +## Getting help + +- **Your shared Slack channel**, for anything time-sensitive during the POC. +- **[support@mintlify.com](mailto:support@mintlify.com)**, for everything else. +- **[Advanced support](/advanced-support)**, if you want to know what support looks like after the POC. + +## After the POC + + + Everything to configure and verify before your documentation goes live for real. + From f524fc7ea9e7b96deb6d595f07a771fff499a92d Mon Sep 17 00:00:00 2001 From: DeweyMarco Date: Mon, 24 Aug 2026 13:24:09 -0700 Subject: [PATCH 2/4] Rework POC steps against the SE working session guides Pulls the mechanics, prerequisites, and objection-handling from the internal SE working sessions into the customer-facing steps. Corrections: - Authentication requires a custom domain or *.mintlify.app subdomain and does not work on .mintlify.site or a custom basepath. The page previously treated the custom domain as skippable during a POC and auth as independent of it. Now flagged in step 1 and step 7. - Separates dashboard SSO (who logs in) from site authentication (who reads), with the real method taxonomy and the two-account test. Additions: - The repo/dashboard/live-site model up front. - Step 4 rewritten with the actual editor flow, plus the point that publishing writes a Git commit so CODEOWNERS and branch protection still apply. - Step 5 gets the docs.json theme keys, the light/dark check, and OG. - Step 6 gets the three-way answer check (answered, correct, which page cited), the description-quality lever, both MCP servers, the contextual menu, and automations. - Sample content chosen from top pages by traffic; two navigation tests; Notion and Confluence sync as a third migration route. - Success criteria reframed as one lever and one metric with a recorded baseline. Co-Authored-By: Claude Opus 5 (1M context) --- poc-onboarding.mdx | 285 +++++++++++++++++++++++++++++++++------------ 1 file changed, 210 insertions(+), 75 deletions(-) diff --git a/poc-onboarding.mdx b/poc-onboarding.mdx index 274492c2a..45326d258 100644 --- a/poc-onboarding.mdx +++ b/poc-onboarding.mdx @@ -1,6 +1,6 @@ --- title: "Proof of concept onboarding" -description: "Set up a Mintlify proof of concept step by step: create your account, connect your repository, migrate sample content, enable the AI assistant, and evaluate the results." +description: "Set up a Mintlify proof of concept step by step: connect your repository, migrate sample content, publish a change, turn on the assistant, and measure the result." keywords: ["POC", "proof of concept", "trial", "evaluation", "enterprise onboarding", "pilot"] noindex: true --- @@ -13,6 +13,16 @@ You do not need to be a developer to finish this guide. Two steps need someone w You have a dedicated Mintlify contact for the duration of your proof of concept (POC). If a step doesn't match what you see on screen, or you get stuck for more than a few minutes, message your shared Slack channel or email [support@mintlify.com](mailto:support@mintlify.com) instead of working around it. +## How Mintlify fits together + +Three things, and knowing which is which makes every step below easier to follow: + +1. **Your repository** is the source of truth. Your documentation is `.mdx` files and one `docs.json` configuration file in Git. Nothing is stored in a proprietary format. +2. **The dashboard** at [app.mintlify.com](https://app.mintlify.com) is the control plane, where you write, configure, and publish. +3. **Your live site** is what readers see. + +The web editor sits between them. When you publish, it writes to your repository for you, so nobody has to run a Git command who doesn't want to. + ## What you'll have at the end @@ -25,7 +35,7 @@ You do not need to be a developer to finish this guide. Two steps need someone w - An assistant answering questions from your documentation, with analytics on what people asked. + An assistant answering questions from your documentation, with analytics showing what people asked and where your content gaps are. @@ -44,44 +54,61 @@ Line these people up before you start. Nothing here needs full-time involvement, | Documentation owner | Runs the POC and completes most steps. This is probably you. | Throughout | A few hours total | | GitHub administrator | Approves the Mintlify GitHub App on your repository. | Step 1 | 15 minutes, once | | Designer or brand owner | Supplies logo files, color codes, and fonts. | Step 5 | 30 minutes, once | -| Identity or IT administrator | Configures single sign-on and DNS records. | Step 7 | 1 to 2 hours, optional | +| Identity or IT administrator | Configures single sign-on, authentication, and DNS records. | Step 7 | 1 to 2 hours, optional | | Decision maker | Reviews the finished POC against your success criteria. | Step 8 | 1 hour | ### What to gather Collect these before step 3 so you aren't waiting on other teams mid-setup: -- Logo files for light and dark backgrounds, in SVG or PNG. -- A favicon, in SVG or PNG. +- Logo files for light and dark backgrounds, in SVG or PNG. You need both variants, or your logo disappears when a reader switches themes. +- A favicon. SVG works well. - Your brand color codes, as hex values. -- Font files, or the names of the Google Fonts you use. +- Font files, or the names of the Google Fonts your marketing site uses. - A link to your current documentation site, or an export of its content. - Your OpenAPI specification file or URL, if you document an API. -- A list of the pages you want in the POC. See [Choose your sample content](#choose-your-sample-content) for how to pick them. +- Your top 20 to 30 pages by traffic, from your current analytics. See [Choose your sample content](#choose-your-sample-content). -### Decide what success looks like +### Pick one thing to prove -Write down three to five criteria before you start, and share them with your Mintlify contact. Without them, the review in step 8 turns into an opinion contest. +Most POCs fail their own review because nobody agreed in advance what a good result looks like. Avoid that by picking a single lever and a single metric under it. -Criteria that work well: + + + Docs shorten time-to-first-success. Metric: activation rate, or time-to-first-integration. + + + + Docs answer the questions your support team gets asked repeatedly. Metric: ticket volume in your top category. + + + + Findable docs unblock the next thing a customer wants to do. Metric: feature adoption after launch. + + + +Write down what "good" would look like for that one metric in 90 days, and share it with your Mintlify contact at kickoff. + + + Record your baseline before you start. If your metric is support tickets, pull the current monthly volume for your top category now. A POC with nothing to compare against produces opinions instead of a decision. + + +Then add two or three practical criteria that the POC itself can settle: - A writer with no Git experience publishes a page change without help. - Our most complex API reference page renders correctly. -- The assistant answers 8 of our 10 most common support questions correctly. +- The assistant answers 8 of our 10 most common support questions correctly, citing the right page. - Our identity provider handles dashboard login. -- A documentation update goes from draft to live in under an hour. ## Step 1: Create your account and connect your repository -Mintlify stores every page as a file in a Git repository, and publishes your site whenever that repository changes. You connect the repository once, at the start, and then mostly forget it exists. - Your GitHub administrator needs organization ownership or administrator permissions on the repository to approve the Mintlify GitHub App. Ask them to be available before you begin this step. Without the app installed, your site will not deploy. - Go to [mintlify.com/start](https://mintlify.com/start) and create an account with your work email address. Use the email address you'd use for your real documentation, not a personal one, so that it maps to your identity provider later. + Go to [mintlify.com/start](https://mintlify.com/start) and create an account with your work email address. Use the address you'd use for your real documentation, not a personal one, so it maps to your identity provider later. @@ -110,7 +137,9 @@ Mintlify stores every page as a file in a Git repository, and publishes your sit - Use the `.mintlify.site` URL for the whole POC. It is a real, working site that you can share internally. Adding your own domain is step 7, and it is not required to evaluate anything. + Use the `.mintlify.site` URL for most of the POC. It is a real, working site you can share internally. + + One exception: if testing authentication is part of your criteria, you need a custom domain or a `*.mintlify.app` subdomain first, because authentication does not work on the default URL or on a custom basepath. Set that up early rather than in the final week. See [step 7](#step-7-loop-in-it-and-security). ## Step 2: Invite your team @@ -133,9 +162,9 @@ For a useful POC, invite at least one writer who has never used Git, one enginee ### Choose your sample content -Pick 20 to 50 pages. More than that slows the POC down without teaching you anything new. +Pull your top 20 to 30 pages by traffic from your current analytics, then pick your sample from that list. Starting from real traffic rather than intuition means you evaluate Mintlify on the pages your readers actually use. -Choose the pages that are hardest to move, not the easiest: +From that list, deliberately include the pages that are hardest to move: - Your most complex API reference page. - A page with a large table or a deeply nested list. @@ -143,7 +172,7 @@ Choose the pages that are hardest to move, not the easiest: - A page using custom components or embedded widgets, if you have any. - Two or three ordinary guides, so you can judge everyday quality. -A POC built on your simplest pages tells you nothing about the migration you'd actually run. +A POC built on your simplest pages tells you nothing about the migration you'd actually run. More than 50 pages slows the POC down without teaching you anything new. ### Move the content @@ -162,16 +191,19 @@ A POC built on your simplest pages tells you nothing about the migration you'd a - Mintlify has tooling for common platforms, and manual instructions for everything else: + Three routes, roughly in order of how clean the result is: - - [Docusaurus](/migration/docusaurus) - - [ReadMe](/migration/readme) - - [GitBook](/migration/gitbook) - - [Fern](/migration/fern) - - [Document360](/migration/document360) - - [Any other platform](/migration/manual) + 1. **Export as Markdown** from your current platform, when it supports that. Mintlify has tooling for [Docusaurus](/migration/docusaurus), [ReadMe](/migration/readme), [GitBook](/migration/gitbook), [Fern](/migration/fern), and [Document360](/migration/document360), plus [manual instructions](/migration/manual) for anything else. + 2. **Paste and clean up in the web editor.** Fastest for a handful of ad-hoc pages. + 3. **Let an AI tool convert it**, using the Mintlify [skill](/ai/skillmd) and [admin MCP server](/ai/mintlify-mcp) in Claude Code or Cursor. - Start at [Migrate to Mintlify](/migration) to pick your path. This route needs someone comfortable running commands in a terminal. + Start at [Migrate to Mintlify](/migration) to pick your path. + + + + If your content lives in Notion, Confluence, Jira, or a similar tool, connect it rather than copying out of it. Connected apps give the Mintlify agent live context and can trigger automations that keep pages aligned with their source. + + See [Integrations for the agent and automations](/automations/integrations) for the full list and setup. @@ -179,6 +211,13 @@ A POC built on your simplest pages tells you nothing about the migration you'd a Open your site and compare each sample page against the same page on your current documentation. Look for missing images, broken tables, code samples that lost their formatting, and links that go nowhere. +While you're there, run two quick tests on your navigation: + +- Can a brand-new user reach their first useful page in two clicks? +- Do your navigation labels match the words someone would type into a search box? "How to configure auth" gets found. "Authentication configuration" often doesn't. + +A no on either one is worth raising now, because your navigation structure lives in `docs.json` and is cheap to change during a POC. + Send anything wrong to your Mintlify contact in one batch rather than one message at a time. Include the page URL and what you expected to see. ## Step 4: Publish a change yourself @@ -186,45 +225,86 @@ Send anything wrong to your Mintlify contact in one batch rather than one messag This is the step that decides most POCs. If your writers can update documentation without filing a ticket with engineering, the tool works for you. Have someone non-technical do this step, not the most technical person on your team. - - Go to the [web editor](https://app.mintlify.com/editor). It looks like a normal document editor and does not require any knowledge of Git. + + Go to the [web editor](https://app.mintlify.com/editor). It has three regions: the **Files** panel on the left with your folders and pages, the editing canvas in the middle, and the toolbar across the top. + + Check the branch selector at the top left before you type anything. When it reads **Live site**, you are editing the deployed site directly and anything you publish goes straight to your readers. - - Open any page and change a sentence. See the [editor tutorial](/editor/tutorial) for a walkthrough of the interface. + + Open the **Live site** dropdown, switch to the **Branches** tab, and select **New branch**. You're now editing a copy, so nothing you do affects readers until you publish. + + Do this for your first edit even if you plan to publish directly later. It's how you'll work day to day, and it means a practice edit can't embarrass you. - - Select **Publish** in the top-right of the toolbar. Your change deploys automatically. + + Click anywhere and start typing, the same way you would in a document. Type `/` to insert a component such as a callout, steps block, or card. Drag an image file onto the canvas and the editor uploads it and writes the reference for you. + + Now use the two toggles at the top right of the canvas: the eye icon shows the rendered page, and the `` icon shows the Markdown source. Your edit is sitting there in the raw `.mdx`, frontmatter and all. + + This matters more than it looks. There's no hidden layer and nothing proprietary, so a writer in the visual view and an engineer in the repository are editing the same file. + - To send changes through review instead of publishing directly, work on a branch and open a pull request. See [Branching and publishing](/editor/branching-and-publishing). + + Copy the branch's preview link and send it to a teammate. They see your change rendered at a live URL, in context, with nothing to install. This is how review works: draft, send the preview, publish once it's approved. - - Watch the deployment status on the **Overview** page of your dashboard, then refresh your site. + + Select **Publish** in the top right. On a branch, publishing opens or updates a pull request. On the live site, it deploys right away. + + Either way, publishing writes a real Git commit. Watch it appear on the **Overview** page of your dashboard, then refresh your site. -Two things worth testing in the same step, because they change how your team works day to day: + + + No. Publishing creates a Git commit, so CODEOWNERS, required reviews, and branch protection all still apply exactly as they do today. Your engineers review documentation changes the same way they review code. Writers just don't need Git to propose one. + -- **Review before publishing.** Every pull request gets its own preview URL that reviewers can open without installing anything. See [Preview deployments](/deploy/preview-deployments). -- **Updating docs from Slack.** Connect the Mintlify agent to your Slack workspace and ask it to make a change. It opens a pull request for you. See [Add the agent to Slack](/agent/slack#connect-your-slack-workspace). + + They can toggle to the Markdown view with the `` icon and stay there. Same content, same file. People on the same team can work in different views without stepping on each other. + + + + They install the [CLI](/cli/install), clone the repository, and run [`mint dev`](/cli/preview) for a local server with hot reload. They can also run `mint broken-links` before pushing, and you can [wire the same checks into CI](/deploy/ci) so a broken link fails the build like a failing test. + + -If your team writes locally in a code editor instead, they can install the [CLI](/cli/install) and preview the site on their own machine with [`mint dev`](/cli/preview). +Two things worth testing in the same sitting, because they change how your team works day to day: + +- **Per-branch previews.** Every pull request gets its own live URL. Reviewers open a link instead of pasting screenshots into chat. See [Preview deployments](/deploy/preview-deployments). +- **Updating docs from Slack.** Connect the Mintlify agent to your Slack workspace and ask it to make a change. It opens a pull request for you. See [Add the agent to Slack](/agent/slack#connect-your-slack-workspace). ## Step 5: Apply your branding -Stakeholders judge the POC partly on whether it looks like your product. This takes about 30 minutes and is worth doing before the review in step 8. +Stakeholders judge a POC partly on whether it looks like your product, and a font mismatch is the first thing anyone notices. This takes about 30 minutes and is worth doing before the review in step 8. + +Almost all of your branding lives in a handful of keys in `docs.json`, so a full brand change is a configuration edit rather than a stylesheet: + +```json docs.json +{ + "theme": "luma", + "colors": { + "primary": "#16A34A", + "light": "#07C983", + "dark": "#15803D" + }, + "logo": { + "light": "/logo/light-logo.svg", + "dark": "/logo/dark-logo.svg" + }, + "favicon": "/favicon.svg" +} +``` + +Set `primary` to your main brand color. `light` and `dark` are the accent shades used in dark and light mode, so tune them until links and buttons stay legible against both backgrounds. Add a `fonts` key to load your marketing font. See [Appearance settings](/organize/settings-appearance) for every option, [Themes](/customize/themes) for the available layouts, and [Fonts](/customize/fonts) for custom typefaces. -Your site's appearance comes from a single configuration file, `docs.json`, in your repository. Set: +Then check both modes, because readers pick their own with the switcher in the top bar: -- **Colors**: Your primary, light, and dark brand colors, as hex values. -- **Logo**: Separate files for light and dark mode. -- **Favicon**: The icon in the browser tab. -- **Fonts**: Google Fonts by name, or your own font files. -- **Theme**: The overall layout and style of the site. +- Your logo needs a light and a dark variant, which is why `logo.light` and `logo.dark` are separate keys. +- Diagrams drawn as SVGs that use `currentColor` recolor themselves. Raster screenshots don't, so keep paired light and dark versions. -See [Appearance settings](/organize/settings-appearance) for every option, [Themes](/customize/themes) for the available layouts, and [Fonts](/customize/fonts) for custom typefaces. +Finally, set a default Open Graph image so links to your docs render a branded card in Slack. Test it in a real Slack message before you share the site widely. See [SEO](/optimize/seo) for the meta tag reference. If editing a configuration file isn't something you want to do, send your brand assets to your Mintlify contact and ask them to apply it. @@ -234,55 +314,107 @@ If editing a configuration file isn't something you want to do, send your brand Configure the assistant on the [Assistant](https://app.mintlify.com/products/assistant) page of your dashboard: -1. Toggle the assistant on. -2. Set your support and sales [deflection emails](/assistant/configure#set-deflection-emails), so that questions the assistant can't answer route to a real person. -3. Add [sample questions](/assistant/configure#add-sample-questions) that show people what to ask. -4. Add [search domains](/assistant/configure#search-domains) if you want the assistant to draw on content outside your documentation site. +1. Turn on the assistant status toggle. +2. Set your support and sales [deflection addresses](/assistant/configure#set-deflection-emails). Do this before you go live. The handoff is what turns a question the assistant can't answer into a clean escalation instead of a dead end. +3. Add up to three [starter questions](/assistant/configure#add-sample-questions) to steer people toward what the assistant answers well. +4. Add [search domains](/assistant/configure#search-domains) if your product spans more than one site. +5. Leave [bot protection](/assistant/configure#bot-protection) on. It's invisible to nearly all real visitors. To change the assistant's tone or teach it product-specific behavior, see [Customize the assistant](/assistant/customize) and [Assistant skills](/assistant/skills). +### Test it against real questions + +Guessing at whether the assistant is good is the most common way to waste a POC. Do this instead: + +1. Pull 20 to 30 real questions from your support tickets or community channels over the last month. +2. Ask each one on your live site using **Ask Assistant** in the top bar. +3. Check every answer three ways: did it answer, was the answer right, and **which page did it cite?** +4. Sort the failures. A wrong answer points at a specific page you should fix. A missing answer points at a page you should write. + +That third check is the one people skip, and it's the one that turns a vague impression into a specific fix. Review what your team and your users asked on the [Assistant analytics](/analytics/assistant) page, where unanswered and downvoted questions become your content backlog. + + + The frontmatter `description` is the single biggest lever on whether a page gets retrieved at all, because the assistant reads it first to decide whether a page is relevant. Aim for 130 to 160 characters of plain language, unique on every page. If a page you know is correct never gets cited, its description is usually why. + + ### Put the assistant where your users are -The [assistant widget](/assistant/widget) embeds the same assistant into your product dashboard, marketing site, or support portal. Adding it needs a developer for about an hour, and it is the fastest way to show your support team what deflection looks like in practice. +The [assistant widget](/assistant/widget) embeds the same assistant into your product dashboard, marketing site, or support portal. Adding it needs a developer for about an hour, and it's the fastest way to show your support team what deflection looks like in practice. -### Confirm your content is ready for AI agents +### Connect your docs to AI tools -Mintlify generates these automatically. Check them, but you don't need to configure anything: +Mintlify runs two MCP servers, and they serve opposite audiences: -- [`llms.txt`](/ai/llmstxt), a machine-readable index of your site. -- [`skill.md`](/ai/skillmd), a description of what agents can do with your product. This can take up to 24 hours to generate. -- An [MCP server](/ai/model-context-protocol) that lets tools like Claude and Cursor search your documentation. -- [Markdown export](/ai/markdown-export), so any page can be copied as clean text into an AI tool. +- The **[search MCP server](/ai/model-context-protocol)** serves your published content to readers inside Claude, Cursor, and ChatGPT. On an authenticated site it respects auth and groups, so each person only retrieves pages their group can see. +- The **[admin MCP server](/ai/mintlify-mcp)** lets your own docs team draft pages, run checks, and edit content from their AI editor. -### Test the assistant properly +For readers who don't use an AI editor, the [contextual menu](/ai/contextual-menu) gives every page a one-click path into ChatGPT, Claude, or Perplexity: -Guessing at whether the assistant is good is the most common way to waste a POC. Do this instead: +```json docs.json +{ + "contextual": { + "options": ["copy", "view", "chatgpt", "claude", "perplexity"] + } +} +``` -1. Pull 20 to 30 real questions from your support tickets or community channels over the last month. -2. Ask the assistant each one. -3. Record whether the answer was correct, partly correct, or wrong. -4. For the wrong answers, check whether your documentation actually contains the answer. Usually it doesn't, and that is a content gap you now know about. +Mintlify also generates [`llms.txt`](/ai/llmstxt) (a map of your pages), [`skill.md`](/ai/skillmd) (what agents can do with your product, which can take up to 24 hours to appear), and a [Markdown version of every page](/ai/markdown-export). Add `.md` to any page URL to see exactly what an AI consumer receives. + +### Automate a maintenance task -Review what your team and your users asked on the [Assistant analytics](/analytics/assistant) page. +Documentation drifts the moment your product moves. [Automations](/automations) run the agent on a schedule, on a push to a repository, or when something happens in a connected tool, and propose the update as a pull request. + +Enable one that maps to something you do by hand today. Drafting a changelog and updating docs from code changes are the clearest starting points. Two settings matter: + +- **How updates are applied.** Start with **Require review** so the automation opens a change and waits for a human. Move low-risk jobs to automatic once you trust them. +- **When it runs.** On content updates, on a schedule, or from pushes in a connected repository. + +Then read the run history and open a run to see the exact change it proposed. That log is how you tell your team the automation is doing the right thing. See [Manage automations](/automations/manage). ## Step 7: Loop in IT and security -Bring your IT or security team in during the POC rather than after it, so their questions don't surface during procurement. Not all of these are needed to evaluate Mintlify, so start with whichever ones appear in your success criteria. +Bring your IT or security team in during the POC rather than after it, so their questions don't surface during procurement. Start with whichever of these appear in your success criteria. + + + Authentication requires a custom domain or a `*.mintlify.app` subdomain. It does **not** work on the default `.mintlify.site` URL or on a custom basepath such as `yourcompany.com/docs`. If gating your documentation is part of the POC, sort the domain out first rather than discovering this in the final week. + -**Who can access your dashboard** +**Who can log into your dashboard** + +This is your team, not your readers. - [Single sign-on](/dashboard/sso) with SAML or OIDC, including Okta, Microsoft Entra, and Google Workspace. - [SCIM provisioning](/dashboard/scim) to create and remove accounts automatically from your identity provider. - [Network access policies](/dashboard/network-access) to restrict dashboard access to your IP ranges. - [Audit logs](/dashboard/audit-logs) and [session security](/dashboard/session-security). -**Who can access your documentation site** +**Who can read your documentation** + +This is your readers. Set the [authentication](/deploy/authentication-setup) method to private, then pick how people sign in: -If your documentation must not be public, set up [authentication](/deploy/authentication-setup). Mintlify supports password protection, OAuth, JWT, and Mintlify-managed private access. You can also [restrict individual pages to specific groups](/deploy/authentication-setup#control-access-with-groups) while leaving the rest of the site public. +- **Password** is the quickest gate to stand up, and fine for a POC. +- **Mintlify-managed access** makes your dashboard organization the user list, with no extra configuration. +- **OAuth 2.0** plugs into the identity provider you already run, and is what most teams end up using. +- **JWT** gives you full programmatic control when your access model is complex. + +Authentication controls who gets in the door. [Groups](/deploy/authentication-setup#control-access-with-groups) control who sees what, set per page in frontmatter: + +```yaml +--- +title: "Production runbook" +groups: ["engineering"] +--- +``` + +Test it with two accounts, not one: sign in as someone in the group and confirm the page appears, then as someone who isn't and confirm it doesn't. That's the difference between access control being enforced and being assumed. + + + A page marked `hidden: true` is only missing from the navigation. Anyone with the URL can still open it, and this page you're reading is a working example of that. Treat hidden as an organization tool. Authentication and groups are the actual gate. See [Hidden pages](/organize/hidden-pages). + **Your domain** -Adding a [custom domain](/customize/custom-domain) needs one DNS record from whoever manages your domain. During a POC, point a test subdomain such as `docs-preview.yourcompany.com` at the site rather than your live documentation domain. Mintlify provisions the TLS certificate automatically. +Adding a [custom domain](/customize/custom-domain) needs one DNS record from whoever manages your domain, and Mintlify provisions the TLS certificate automatically. During a POC, point a test subdomain such as `docs-preview.yourcompany.com` at the site rather than your live documentation domain. **Analytics, checks, and compliance** @@ -292,15 +424,18 @@ Adding a [custom domain](/customize/custom-domain) needs one DNS record from who ## Step 8: Review the results -Book an hour with your decision maker and walk through your criteria from [Decide what success looks like](#decide-what-success-looks-like). Use the evidence you collected rather than impressions. +Book an hour with your decision maker. Open with the one metric you picked in [Pick one thing to prove](#pick-one-thing-to-prove) and the baseline you recorded, then walk the evidence you collected. | What you're checking | Where to check it | |---|---| | A non-developer can publish independently | Whether step 4 worked without help, and how long it took | +| Engineers keep their review process | The pull request your editor change opened, with your existing checks on it | | Your hardest content survived the move | Your sample pages, compared side by side with your current site | -| The assistant answers accurately | Your scored question list, plus [Assistant analytics](/analytics/assistant) | +| The assistant answers accurately | Your scored question list, including which page each answer cited | +| Where your content gaps are | Unanswered and downvoted questions in [Assistant analytics](/analytics/assistant) | | Readers find what they need | [Traffic](/analytics/traffic), [search](/analytics/search), and [engagement](/analytics/user-engagements) analytics | | Readers say it's better | [Page feedback](/optimize/feedback) | +| Docs stay current without manual work | The run history of the automation you enabled in step 6 | | It meets security requirements | Your IT team's sign-off from step 7 | Bring open questions to your Mintlify contact before the review, not during it. @@ -311,8 +446,8 @@ Most POCs run two to three weeks. Compressing this into a few days is possible, | Week | What happens | |---|---| -| Week 1 | Steps 1 and 2: account, repository, and team. Send your content sample to be migrated, or start migrating it. Agree on success criteria. | -| Week 2 | Steps 3 to 6: review the migrated content, publish changes yourself, apply branding, and turn on the assistant. Start collecting your assistant test questions. | +| Week 1 | Steps 1 and 2: account, repository, and team. Send your content sample to be migrated, or start migrating it. Agree the one metric and record its baseline. If authentication is in scope, start the custom domain now. | +| Week 2 | Steps 3 to 6: review the migrated content, publish a change yourself, apply branding, turn on the assistant, and enable one automation. Start scoring your assistant test questions. | | Week 3 | Steps 7 and 8: IT and security review, then the results review with your decision maker. | ## Getting help From 34ca0461d083151c2bd9db72616c7ad82b804f89 Mon Sep 17 00:00:00 2001 From: DeweyMarco Date: Tue, 25 Aug 2026 09:04:37 -0700 Subject: [PATCH 3/4] Tighten POC onboarding for house style Editorial pass by Marco. Cuts roughly a third of the page: replaces the conversational framing with a workflow table up front, converts the intro card grids to prose and tables, and trims each step to the action and its outcome. All substance retained, including the authentication domain requirement and the split between dashboard access and documentation access. Co-Authored-By: Claude Opus 5 (1M context) --- poc-onboarding.mdx | 471 ++++++++++++++++++--------------------------- 1 file changed, 189 insertions(+), 282 deletions(-) diff --git a/poc-onboarding.mdx b/poc-onboarding.mdx index 45326d258..ede7b4d6f 100644 --- a/poc-onboarding.mdx +++ b/poc-onboarding.mdx @@ -1,285 +1,219 @@ --- -title: "Proof of concept onboarding" -description: "Set up a Mintlify proof of concept step by step: connect your repository, migrate sample content, publish a change, turn on the assistant, and measure the result." +title: "POC onboarding" +description: "Set up and evaluate a Mintlify proof of concept, from connecting your repository to reviewing publishing, AI, and security workflows." keywords: ["POC", "proof of concept", "trial", "evaluation", "enterprise onboarding", "pilot"] noindex: true --- -This guide takes you from nothing to a working Mintlify documentation site that your team can evaluate. Follow the steps in order. Each one tells you what to do, who you need from your team, and how long it takes. - -You do not need to be a developer to finish this guide. Two steps need someone with GitHub or IT access for a short time. You can do everything else yourself in a browser. +Use this guide to set up a working documentation site and evaluate Mintlify with your team. Most tasks happen in the dashboard, but you need brief help from GitHub and IT administrators for some steps. - You have a dedicated Mintlify contact for the duration of your proof of concept (POC). If a step doesn't match what you see on screen, or you get stuck for more than a few minutes, message your shared Slack channel or email [support@mintlify.com](mailto:support@mintlify.com) instead of working around it. + If you get stuck, contact your Mintlify representative in your shared Slack channel or email [support@mintlify.com](mailto:support@mintlify.com). -## How Mintlify fits together - -Three things, and knowing which is which makes every step below easier to follow: - -1. **Your repository** is the source of truth. Your documentation is `.mdx` files and one `docs.json` configuration file in Git. Nothing is stored in a proprietary format. -2. **The dashboard** at [app.mintlify.com](https://app.mintlify.com) is the control plane, where you write, configure, and publish. -3. **Your live site** is what readers see. - -The web editor sits between them. When you publish, it writes to your repository for you, so nobody has to run a Git command who doesn't want to. +## POC workflow -## What you'll have at the end +Complete these steps in order: - - - A real site at your own URL, running a representative sample of your content. - - - - Your team editing and publishing pages, with review before anything goes live. - - - - An assistant answering questions from your documentation, with analytics showing what people asked and where your content gaps are. - +| Step | Outcome | +|---|---| +| 1. Connect your repository | Deploy a starter site. | +| 2. Invite your team | Give participants the access they need. | +| 3. Add sample content | Test representative and complex pages. | +| 4. Publish a change | Verify your writing and review workflow. | +| 5. Apply branding | Match the site to your product. | +| 6. Test AI features | Evaluate assistant answers and one AI workflow. | +| 7. Review security | Confirm authentication and compliance requirements. | +| 8. Review results | Compare the POC against your success criteria. | - - Single sign-on, access controls, and audit logging configured or confirmed. - - +Your repository remains the source of truth. The dashboard lets you edit, configure, and publish the `.mdx` files and `docs.json` configuration in that repository. Your live site displays the published result. ## Before you begin -### People you'll need +### Identify participants -Line these people up before you start. Nothing here needs full-time involvement, but a missing GitHub administrator can stall the POC for days. +| Participant | Responsibility | Time needed | +|---|---|---| +| Documentation owner | Runs the POC and completes most steps. | A few hours total | +| GitHub administrator | Approves the Mintlify GitHub App. | 15 minutes | +| Designer or brand owner | Provides logos, colors, and fonts. | 30 minutes | +| Identity or IT administrator | Configures authentication and DNS, if required. | 1 to 2 hours | +| Decision maker | Reviews the POC against your success criteria. | 1 hour | -| Who | What they do | When | Time needed | -|---|---|---|---| -| Documentation owner | Runs the POC and completes most steps. This is probably you. | Throughout | A few hours total | -| GitHub administrator | Approves the Mintlify GitHub App on your repository. | Step 1 | 15 minutes, once | -| Designer or brand owner | Supplies logo files, color codes, and fonts. | Step 5 | 30 minutes, once | -| Identity or IT administrator | Configures single sign-on, authentication, and DNS records. | Step 7 | 1 to 2 hours, optional | -| Decision maker | Reviews the finished POC against your success criteria. | Step 8 | 1 hour | +### Gather your content and brand assets -### What to gather +Collect: -Collect these before step 3 so you aren't waiting on other teams mid-setup: +- Light and dark logo variants in SVG or PNG format. +- A favicon, preferably in SVG format. +- Brand colors as hex values. +- Font files or the names of your Google Fonts. +- A link to your current documentation or a content export. +- Your OpenAPI file or URL, if you document an API. +- Your 20 to 30 highest-traffic pages. -- Logo files for light and dark backgrounds, in SVG or PNG. You need both variants, or your logo disappears when a reader switches themes. -- A favicon. SVG works well. -- Your brand color codes, as hex values. -- Font files, or the names of the Google Fonts your marketing site uses. -- A link to your current documentation site, or an export of its content. -- Your OpenAPI specification file or URL, if you document an API. -- Your top 20 to 30 pages by traffic, from your current analytics. See [Choose your sample content](#choose-your-sample-content). +### Define success -### Pick one thing to prove +Choose one business goal and record its current baseline: -Most POCs fail their own review because nobody agreed in advance what a good result looks like. Avoid that by picking a single lever and a single metric under it. +- **Acquisition:** Improve activation rate or time to first integration. +- **Deflection:** Reduce ticket volume for a common support topic. +- **Retention:** Increase adoption of a feature after launch. - - - Docs shorten time-to-first-success. Metric: activation rate, or time-to-first-integration. - +Add two or three criteria that you can test during the POC. For example: - - Docs answer the questions your support team gets asked repeatedly. Metric: ticket volume in your top category. - +- A writer without Git experience can publish a change without help. +- Your most complex API reference page renders correctly. +- The assistant answers 8 of 10 common support questions and cites the correct pages. +- Your identity provider supports dashboard login. - - Findable docs unblock the next thing a customer wants to do. Metric: feature adoption after launch. - - +Share the goal, baseline, and criteria with your Mintlify representative. -Write down what "good" would look like for that one metric in 90 days, and share it with your Mintlify contact at kickoff. - - - Record your baseline before you start. If your metric is support tickets, pull the current monthly volume for your top category now. A POC with nothing to compare against produces opinions instead of a decision. - - -Then add two or three practical criteria that the POC itself can settle: - -- A writer with no Git experience publishes a page change without help. -- Our most complex API reference page renders correctly. -- The assistant answers 8 of our 10 most common support questions correctly, citing the right page. -- Our identity provider handles dashboard login. - -## Step 1: Create your account and connect your repository +## Step 1: Connect your repository - Your GitHub administrator needs organization ownership or administrator permissions on the repository to approve the Mintlify GitHub App. Ask them to be available before you begin this step. Without the app installed, your site will not deploy. + A GitHub organization owner or repository administrator must approve the Mintlify GitHub App before your site can deploy. - - Go to [mintlify.com/start](https://mintlify.com/start) and create an account with your work email address. Use the address you'd use for your real documentation, not a personal one, so it maps to your identity provider later. + + Go to [mintlify.com/start](https://mintlify.com/start) and sign up with your work email address. - - During onboarding, connect your GitHub account, then create a new repository or select an existing empty one. A repository named `docs` inside your company's GitHub organization is a good default. A private repository is fine. + + Connect GitHub during onboarding. Create a repository or select an empty one in your company organization. A private repository named `docs` is a common choice. - Do not select a repository that already contains an application or other files. + Do not select a repository that contains application code or unrelated files. - Your GitHub administrator installs the Mintlify GitHub App and grants it access to that one repository. Select **Only select repositories** rather than granting access to everything. + Ask your GitHub administrator to install the Mintlify GitHub App. Grant access to the documentation repository by selecting **Only select repositories**. - See [Install the GitHub App](/deploy/github#install-the-github-app) for the exact permissions the app requests. Send that link to your administrator ahead of time if they want to review the permissions first. + See [Install the GitHub App](/deploy/github#install-the-github-app) for the requested permissions. - - Install the app anyway. GitHub sends an approval request to your organization owners, and the installation completes when they approve it. + + If you cannot approve the app, submit the installation request. GitHub notifies your organization owners. - If that approval will take days, you can skip connecting a Git provider during onboarding. Mintlify creates a private repository for you so you can start immediately, and you can move the content to your own repository later from the [Git settings](https://app.mintlify.com/settings/deployment/git-settings) page. See [Clone to your own repository](/deploy/github#clone-to-your-own-repository). + To continue while approval is pending, skip the Git provider during onboarding. Mintlify creates a private repository that you can later move from [Git settings](https://app.mintlify.com/settings/deployment/git-settings). See [Clone to your own repository](/deploy/github#clone-to-your-own-repository). - - Mintlify deploys starter content to your repository and publishes it. Your site is live at `https://.mintlify.site`. - - Find the exact URL on the **Overview** page of your [dashboard](https://app.mintlify.com/). Open it to confirm the site loads. + + After the starter content deploys, find your URL on the **Overview** page of the [dashboard](https://app.mintlify.com/). Open the `https://.mintlify.site` URL and confirm that it loads. - - Use the `.mintlify.site` URL for most of the POC. It is a real, working site you can share internally. - - One exception: if testing authentication is part of your criteria, you need a custom domain or a `*.mintlify.app` subdomain first, because authentication does not work on the default URL or on a custom basepath. Set that up early rather than in the final week. See [step 7](#step-7-loop-in-it-and-security). - +Use the `.mintlify.site` URL during the POC unless you need to test authentication. Authentication requires a custom domain or `*.mintlify.app` subdomain. ## Step 2: Invite your team -Add everyone who needs to see or touch the POC from the [Members](https://app.mintlify.com/settings/organization/members) page of your dashboard. +Open the [Members](https://app.mintlify.com/settings/organization/members) page and assign the narrowest role each participant needs: -Mintlify has three roles. Assign the narrowest one that lets each person do their job: +- **Admin:** Manages organization settings, billing, and integrations. +- **Editor:** Creates and publishes content. +- **Viewer:** Reviews the dashboard and analytics without editing. -- **Admin**: Changes organization settings, billing, and integrations. Give this to yourself and one backup. -- **Editor**: Creates and publishes content. Give this to your writers. -- **Viewer**: Reads the dashboard and analytics without editing. Give this to reviewers and stakeholders. +See [Roles](/dashboard/roles) for a complete permissions list. -See [Roles](/dashboard/roles) for what each role can do in detail. +Invite at least one writer who does not use Git, one engineer, and the decision maker. Use their work email addresses so their accounts can connect to your identity provider during step 7. -Invite people using their work email addresses. If you plan to test single sign-on in step 7, mismatched addresses mean their accounts will not link to your identity provider. +## Step 3: Add sample content -For a useful POC, invite at least one writer who has never used Git, one engineer, and the person who will make the buying decision. The first two tell you whether the tool fits your team. The third needs to have seen it work. +### Choose representative pages -## Step 3: Get your content in - -### Choose your sample content - -Pull your top 20 to 30 pages by traffic from your current analytics, then pick your sample from that list. Starting from real traffic rather than intuition means you evaluate Mintlify on the pages your readers actually use. - -From that list, deliberately include the pages that are hardest to move: +Start with your 20 to 30 highest-traffic pages. Include: - Your most complex API reference page. -- A page with a large table or a deeply nested list. +- A page with a large table or deeply nested list. - A page with images, video, or diagrams. -- A page using custom components or embedded widgets, if you have any. -- Two or three ordinary guides, so you can judge everyday quality. +- A page with custom components or embedded widgets. +- Two or three typical guides. -A POC built on your simplest pages tells you nothing about the migration you'd actually run. More than 50 pages slows the POC down without teaching you anything new. +Keep the sample under 50 pages so you can focus on migration quality. ### Move the content - - Ask your Mintlify contact whether a migration is included in your POC, and what the turnaround time is. + + Ask your Mintlify representative whether migration is included in your POC. If it is, send: - If it is, send them: + - Your current documentation URL or export. + - Your list of sample pages. + - Your OpenAPI file or URL, if applicable. + - Your brand assets. - - A link to your current documentation site, or an export of its content. - - The list of pages you chose. - - Your OpenAPI specification file or URL, if you have an API reference. - - Your brand assets from [What to gather](#what-to-gather). - - Mintlify ports the content, checks it, and shares a preview link so you can watch progress. See [Enterprise migrations](/migration-services/enterprise) for how the full migration process works after the POC. + See [Enterprise migrations](/migration-services/enterprise) for the full migration process. - Three routes, roughly in order of how clean the result is: + Use one of these methods: - 1. **Export as Markdown** from your current platform, when it supports that. Mintlify has tooling for [Docusaurus](/migration/docusaurus), [ReadMe](/migration/readme), [GitBook](/migration/gitbook), [Fern](/migration/fern), and [Document360](/migration/document360), plus [manual instructions](/migration/manual) for anything else. - 2. **Paste and clean up in the web editor.** Fastest for a handful of ad-hoc pages. - 3. **Let an AI tool convert it**, using the Mintlify [skill](/ai/skillmd) and [admin MCP server](/ai/mintlify-mcp) in Claude Code or Cursor. + 1. Export Markdown from your current platform. Follow the migration guide for [Docusaurus](/migration/docusaurus), [ReadMe](/migration/readme), [GitBook](/migration/gitbook), [Fern](/migration/fern), or [Document360](/migration/document360). + 2. Paste a small number of pages into the web editor and clean up the formatting. + 3. Convert content with an AI tool using the Mintlify [skill](/ai/skillmd) and [admin MCP server](/ai/mintlify-mcp). - Start at [Migrate to Mintlify](/migration) to pick your path. + See [Migrate to Mintlify](/migration) for other platforms. - - If your content lives in Notion, Confluence, Jira, or a similar tool, connect it rather than copying out of it. Connected apps give the Mintlify agent live context and can trigger automations that keep pages aligned with their source. - - See [Integrations for the agent and automations](/automations/integrations) for the full list and setup. + + If your source content lives in Notion, Confluence, Jira, or a similar tool, connect it to the Mintlify agent. See [Integrations for the agent and automations](/automations/integrations). -### Check the result - -Open your site and compare each sample page against the same page on your current documentation. Look for missing images, broken tables, code samples that lost their formatting, and links that go nowhere. +### Review the migration -While you're there, run two quick tests on your navigation: +Compare each sample page with its source. Check: -- Can a brand-new user reach their first useful page in two clicks? -- Do your navigation labels match the words someone would type into a search box? "How to configure auth" gets found. "Authentication configuration" often doesn't. +- Images, tables, and code samples. +- Internal and external links. +- Custom components and embeds. +- Navigation labels and page placement. -A no on either one is worth raising now, because your navigation structure lives in `docs.json` and is cheap to change during a POC. +Confirm that a new user can reach a useful page in two clicks and that navigation labels use terms readers are likely to search for. Send migration issues to your Mintlify representative in one list with the page URL and expected result. -Send anything wrong to your Mintlify contact in one batch rather than one message at a time. Include the page URL and what you expected to see. +## Step 4: Publish a change -## Step 4: Publish a change yourself - -This is the step that decides most POCs. If your writers can update documentation without filing a ticket with engineering, the tool works for you. Have someone non-technical do this step, not the most technical person on your team. +Ask a writer who does not use Git to complete this step. - - Go to the [web editor](https://app.mintlify.com/editor). It has three regions: the **Files** panel on the left with your folders and pages, the editing canvas in the middle, and the toolbar across the top. - - Check the branch selector at the top left before you type anything. When it reads **Live site**, you are editing the deployed site directly and anything you publish goes straight to your readers. - + + Open the [web editor](https://app.mintlify.com/editor). Select the **Live site** dropdown, open the **Branches** tab, and select **New branch**. - - Open the **Live site** dropdown, switch to the **Branches** tab, and select **New branch**. You're now editing a copy, so nothing you do affects readers until you publish. - - Do this for your first edit even if you plan to publish directly later. It's how you'll work day to day, and it means a practice edit can't embarrass you. + A branch keeps the draft separate from your deployed site. - - Click anywhere and start typing, the same way you would in a document. Type `/` to insert a component such as a callout, steps block, or card. Drag an image file onto the canvas and the editor uploads it and writes the reference for you. - - Now use the two toggles at the top right of the canvas: the eye icon shows the rendered page, and the `` icon shows the Markdown source. Your edit is sitting there in the raw `.mdx`, frontmatter and all. + + Edit the page in the visual editor. Type `/` to insert a component or drag an image onto the page to upload it. - This matters more than it looks. There's no hidden layer and nothing proprietary, so a writer in the visual view and an engineer in the repository are editing the same file. + Use the eye icon to preview the rendered page and the `` icon to view its MDX source. - - Copy the branch's preview link and send it to a teammate. They see your change rendered at a live URL, in context, with nothing to install. This is how review works: draft, send the preview, publish once it's approved. + + Copy the branch preview URL and send it to a reviewer. Make any requested changes on the same branch. - Select **Publish** in the top right. On a branch, publishing opens or updates a pull request. On the live site, it deploys right away. + Select **Publish**. Publishing from a branch opens or updates a pull request. Publishing from **Live site** deploys the change immediately. - Either way, publishing writes a real Git commit. Watch it appear on the **Overview** page of your dashboard, then refresh your site. + Confirm that the commit appears on the dashboard **Overview** page and that the approved change appears on your site. - - No. Publishing creates a Git commit, so CODEOWNERS, required reviews, and branch protection all still apply exactly as they do today. Your engineers review documentation changes the same way they review code. Writers just don't need Git to propose one. - - - - They can toggle to the Markdown view with the `` icon and stay there. Same content, same file. People on the same team can work in different views without stepping on each other. + + Editor changes create Git commits, so CODEOWNERS, required reviews, and branch protection continue to apply. - - They install the [CLI](/cli/install), clone the repository, and run [`mint dev`](/cli/preview) for a local server with hot reload. They can also run `mint broken-links` before pushing, and you can [wire the same checks into CI](/deploy/ci) so a broken link fails the build like a failing test. + + Writers can stay in the editor's Markdown view. Engineers can install the [CLI](/cli/install), clone the repository, and run [`mint dev`](/cli/preview) locally. -Two things worth testing in the same sitting, because they change how your team works day to day: - -- **Per-branch previews.** Every pull request gets its own live URL. Reviewers open a link instead of pasting screenshots into chat. See [Preview deployments](/deploy/preview-deployments). -- **Updating docs from Slack.** Connect the Mintlify agent to your Slack workspace and ask it to make a change. It opens a pull request for you. See [Add the agent to Slack](/agent/slack#connect-your-slack-workspace). +You can also test [preview deployments](/deploy/preview-deployments) for pull requests or [add the agent to Slack](/agent/slack#connect-your-slack-workspace) to propose documentation changes from Slack. ## Step 5: Apply your branding -Stakeholders judge a POC partly on whether it looks like your product, and a font mismatch is the first thing anyone notices. This takes about 30 minutes and is worth doing before the review in step 8. - -Almost all of your branding lives in a handful of keys in `docs.json`, so a full brand change is a configuration edit rather than a stylesheet: +Update your brand settings in `docs.json`: ```json docs.json { @@ -297,107 +231,84 @@ Almost all of your branding lives in a handful of keys in `docs.json`, so a full } ``` -Set `primary` to your main brand color. `light` and `dark` are the accent shades used in dark and light mode, so tune them until links and buttons stay legible against both backgrounds. Add a `fonts` key to load your marketing font. See [Appearance settings](/organize/settings-appearance) for every option, [Themes](/customize/themes) for the available layouts, and [Fonts](/customize/fonts) for custom typefaces. - -Then check both modes, because readers pick their own with the switcher in the top bar: - -- Your logo needs a light and a dark variant, which is why `logo.light` and `logo.dark` are separate keys. -- Diagrams drawn as SVGs that use `currentColor` recolor themselves. Raster screenshots don't, so keep paired light and dark versions. - -Finally, set a default Open Graph image so links to your docs render a branded card in Slack. Test it in a real Slack message before you share the site widely. See [SEO](/optimize/seo) for the meta tag reference. - -If editing a configuration file isn't something you want to do, send your brand assets to your Mintlify contact and ask them to apply it. +Then: -## Step 6: Turn on the AI features +1. Check that links and buttons remain legible in light and dark mode. +2. Add your fonts using the [font settings](/customize/fonts). +3. Add a default Open Graph image and test a shared link in Slack. -### Enable the assistant +See [Appearance settings](/organize/settings-appearance), [Themes](/customize/themes), and [SEO](/optimize/seo) for other options. If you do not want to edit `docs.json`, send your assets to your Mintlify representative. -Configure the assistant on the [Assistant](https://app.mintlify.com/products/assistant) page of your dashboard: +## Step 6: Test AI features -1. Turn on the assistant status toggle. -2. Set your support and sales [deflection addresses](/assistant/configure#set-deflection-emails). Do this before you go live. The handoff is what turns a question the assistant can't answer into a clean escalation instead of a dead end. -3. Add up to three [starter questions](/assistant/configure#add-sample-questions) to steer people toward what the assistant answers well. -4. Add [search domains](/assistant/configure#search-domains) if your product spans more than one site. -5. Leave [bot protection](/assistant/configure#bot-protection) on. It's invisible to nearly all real visitors. +### Configure the assistant -To change the assistant's tone or teach it product-specific behavior, see [Customize the assistant](/assistant/customize) and [Assistant skills](/assistant/skills). +Open the [Assistant](https://app.mintlify.com/products/assistant) page: -### Test it against real questions +1. Turn on the assistant. +2. Add [deflection email addresses](/assistant/configure#set-deflection-emails) for questions that need human help. +3. Add up to three [starter questions](/assistant/configure#add-sample-questions). +4. Add [search domains](/assistant/configure#search-domains) if relevant content spans multiple sites. +5. Leave [bot protection](/assistant/configure#bot-protection) enabled. -Guessing at whether the assistant is good is the most common way to waste a POC. Do this instead: +See [Customize the assistant](/assistant/customize) and [Assistant skills](/assistant/skills) for product-specific instructions and tone. -1. Pull 20 to 30 real questions from your support tickets or community channels over the last month. -2. Ask each one on your live site using **Ask Assistant** in the top bar. -3. Check every answer three ways: did it answer, was the answer right, and **which page did it cite?** -4. Sort the failures. A wrong answer points at a specific page you should fix. A missing answer points at a page you should write. +### Test real questions -That third check is the one people skip, and it's the one that turns a vague impression into a specific fix. Review what your team and your users asked on the [Assistant analytics](/analytics/assistant) page, where unanswered and downvoted questions become your content backlog. +1. Collect 20 to 30 recent questions from support tickets or community channels. +2. Ask each question through **Ask Assistant** on your site. +3. Record whether the answer is correct and cites the right page. +4. Use wrong or missing answers to identify pages to update or create. - - The frontmatter `description` is the single biggest lever on whether a page gets retrieved at all, because the assistant reads it first to decide whether a page is relevant. Aim for 130 to 160 characters of plain language, unique on every page. If a page you know is correct never gets cited, its description is usually why. - +Review unanswered and downvoted questions in [Assistant analytics](/analytics/assistant). If a relevant page is not cited, make its frontmatter `description` specific and unique. -### Put the assistant where your users are +### Test one additional AI workflow -The [assistant widget](/assistant/widget) embeds the same assistant into your product dashboard, marketing site, or support portal. Adding it needs a developer for about an hour, and it's the fastest way to show your support team what deflection looks like in practice. +Choose the workflow most relevant to your evaluation: -### Connect your docs to AI tools - -Mintlify runs two MCP servers, and they serve opposite audiences: - -- The **[search MCP server](/ai/model-context-protocol)** serves your published content to readers inside Claude, Cursor, and ChatGPT. On an authenticated site it respects auth and groups, so each person only retrieves pages their group can see. -- The **[admin MCP server](/ai/mintlify-mcp)** lets your own docs team draft pages, run checks, and edit content from their AI editor. - -For readers who don't use an AI editor, the [contextual menu](/ai/contextual-menu) gives every page a one-click path into ChatGPT, Claude, or Perplexity: - -```json docs.json -{ - "contextual": { - "options": ["copy", "view", "chatgpt", "claude", "perplexity"] - } -} -``` - -Mintlify also generates [`llms.txt`](/ai/llmstxt) (a map of your pages), [`skill.md`](/ai/skillmd) (what agents can do with your product, which can take up to 24 hours to appear), and a [Markdown version of every page](/ai/markdown-export). Add `.md` to any page URL to see exactly what an AI consumer receives. - -### Automate a maintenance task - -Documentation drifts the moment your product moves. [Automations](/automations) run the agent on a schedule, on a push to a repository, or when something happens in a connected tool, and propose the update as a pull request. + + + Add the [assistant widget](/assistant/widget) to your product, marketing site, or support portal. + -Enable one that maps to something you do by hand today. Drafting a changelog and updating docs from code changes are the clearest starting points. Two settings matter: + + Use the [search MCP server](/ai/model-context-protocol) to make published content available in supported AI tools. Use the [admin MCP server](/ai/mintlify-mcp) to draft and edit documentation. -- **How updates are applied.** Start with **Require review** so the automation opens a change and waits for a human. Move low-risk jobs to automatic once you trust them. -- **When it runs.** On content updates, on a schedule, or from pushes in a connected repository. + You can also test the [contextual menu](/ai/contextual-menu), [`llms.txt`](/ai/llmstxt), [`skill.md`](/ai/skillmd), and [Markdown page export](/ai/markdown-export). + -Then read the run history and open a run to see the exact change it proposed. That log is how you tell your team the automation is doing the right thing. See [Manage automations](/automations/manage). + + Enable one [automation](/automations), such as drafting a changelog or updating documentation after a code change. Start with **Require review**, then inspect its proposed pull request and run history. See [Manage automations](/automations/manage). + + -## Step 7: Loop in IT and security +## Step 7: Review IT and security requirements -Bring your IT or security team in during the POC rather than after it, so their questions don't surface during procurement. Start with whichever of these appear in your success criteria. +Bring your IT or security team into the POC before the final review. - Authentication requires a custom domain or a `*.mintlify.app` subdomain. It does **not** work on the default `.mintlify.site` URL or on a custom basepath such as `yourcompany.com/docs`. If gating your documentation is part of the POC, sort the domain out first rather than discovering this in the final week. + Site authentication does not work on the default `.mintlify.site` URL or on a custom basepath such as `yourcompany.com/docs`. Use a custom domain or `*.mintlify.app` subdomain. -**Who can log into your dashboard** +### Control dashboard access -This is your team, not your readers. +Evaluate the controls your team requires: -- [Single sign-on](/dashboard/sso) with SAML or OIDC, including Okta, Microsoft Entra, and Google Workspace. -- [SCIM provisioning](/dashboard/scim) to create and remove accounts automatically from your identity provider. -- [Network access policies](/dashboard/network-access) to restrict dashboard access to your IP ranges. +- [Single sign-on](/dashboard/sso) with SAML or OIDC. +- [SCIM provisioning](/dashboard/scim). +- [Network access policies](/dashboard/network-access). - [Audit logs](/dashboard/audit-logs) and [session security](/dashboard/session-security). -**Who can read your documentation** +### Control documentation access -This is your readers. Set the [authentication](/deploy/authentication-setup) method to private, then pick how people sign in: +Configure [authentication](/deploy/authentication-setup) for your readers: -- **Password** is the quickest gate to stand up, and fine for a POC. -- **Mintlify-managed access** makes your dashboard organization the user list, with no extra configuration. -- **OAuth 2.0** plugs into the identity provider you already run, and is what most teams end up using. -- **JWT** gives you full programmatic control when your access model is complex. +- **Password:** Quick access control for a POC. +- **Mintlify-managed access:** Uses your dashboard organization as the user list. +- **OAuth 2.0:** Connects to your identity provider. +- **JWT:** Supports custom programmatic access models. -Authentication controls who gets in the door. [Groups](/deploy/authentication-setup#control-access-with-groups) control who sees what, set per page in frontmatter: +Use [groups](/deploy/authentication-setup#control-access-with-groups) to restrict specific pages: ```yaml --- @@ -406,58 +317,54 @@ groups: ["engineering"] --- ``` -Test it with two accounts, not one: sign in as someone in the group and confirm the page appears, then as someone who isn't and confirm it doesn't. That's the difference between access control being enforced and being assumed. +Test with one account in the group and one account outside it. - A page marked `hidden: true` is only missing from the navigation. Anyone with the URL can still open it, and this page you're reading is a working example of that. Treat hidden as an organization tool. Authentication and groups are the actual gate. See [Hidden pages](/organize/hidden-pages). + `hidden: true` removes a page from navigation but does not restrict access. Use authentication and groups for access control. See [Hidden pages](/organize/hidden-pages). -**Your domain** - -Adding a [custom domain](/customize/custom-domain) needs one DNS record from whoever manages your domain, and Mintlify provisions the TLS certificate automatically. During a POC, point a test subdomain such as `docs-preview.yourcompany.com` at the site rather than your live documentation domain. - -**Analytics, checks, and compliance** +### Complete infrastructure and compliance checks -- Connect your existing [analytics platform](/integrations/analytics/overview) so documentation traffic lands in the tools you already use. -- Enable [CI checks](/deploy/ci) to catch broken links and accessibility problems before they publish. -- For security questionnaires, certifications, and contract review, see [Enterprise contracting](/enterprise-contracting). +- Add a [custom domain](/customize/custom-domain). Use a test subdomain during the POC. +- Connect your [analytics platform](/integrations/analytics/overview). +- Enable [CI checks](/deploy/ci) for links and accessibility. +- Share [Enterprise contracting](/enterprise-contracting) with security and procurement teams. ## Step 8: Review the results -Book an hour with your decision maker. Open with the one metric you picked in [Pick one thing to prove](#pick-one-thing-to-prove) and the baseline you recorded, then walk the evidence you collected. +Book one hour with your decision maker. Start with the goal and baseline you defined before the POC, then review: -| What you're checking | Where to check it | +| Criterion | Evidence | |---|---| -| A non-developer can publish independently | Whether step 4 worked without help, and how long it took | -| Engineers keep their review process | The pull request your editor change opened, with your existing checks on it | -| Your hardest content survived the move | Your sample pages, compared side by side with your current site | -| The assistant answers accurately | Your scored question list, including which page each answer cited | -| Where your content gaps are | Unanswered and downvoted questions in [Assistant analytics](/analytics/assistant) | -| Readers find what they need | [Traffic](/analytics/traffic), [search](/analytics/search), and [engagement](/analytics/user-engagements) analytics | -| Readers say it's better | [Page feedback](/optimize/feedback) | -| Docs stay current without manual work | The run history of the automation you enabled in step 6 | -| It meets security requirements | Your IT team's sign-off from step 7 | +| A non-developer can publish | The step 4 result and time required. | +| Engineers keep review control | The pull request and its checks. | +| Complex content migrates correctly | Side-by-side sample pages. | +| The assistant answers accurately | Your scored questions and cited pages. | +| Content gaps are identifiable | Unanswered and downvoted questions in [Assistant analytics](/analytics/assistant). | +| Readers find useful content | [Traffic](/analytics/traffic), [search](/analytics/search), and [engagement](/analytics/user-engagements) data. | +| Automated updates are useful | The automation run history and proposed change. | +| Security requirements are met | Your IT team's review. | -Bring open questions to your Mintlify contact before the review, not during it. +Resolve open questions with your Mintlify representative before this meeting. -## A workable timeline +## Suggested timeline -Most POCs run two to three weeks. Compressing this into a few days is possible, but only if your GitHub administrator and brand assets are ready on day one. +Most POCs take two to three weeks: -| Week | What happens | +| Week | Focus | |---|---| -| Week 1 | Steps 1 and 2: account, repository, and team. Send your content sample to be migrated, or start migrating it. Agree the one metric and record its baseline. If authentication is in scope, start the custom domain now. | -| Week 2 | Steps 3 to 6: review the migrated content, publish a change yourself, apply branding, turn on the assistant, and enable one automation. Start scoring your assistant test questions. | -| Week 3 | Steps 7 and 8: IT and security review, then the results review with your decision maker. | +| Week 1 | Connect the repository, invite your team, define success, and start the content migration. Start domain setup if you need authentication. | +| Week 2 | Review content, publish a change, apply branding, test the assistant, and evaluate one AI workflow. | +| Week 3 | Complete the IT and security review, then review the results with your decision maker. | ## Getting help -- **Your shared Slack channel**, for anything time-sensitive during the POC. -- **[support@mintlify.com](mailto:support@mintlify.com)**, for everything else. -- **[Advanced support](/advanced-support)**, if you want to know what support looks like after the POC. +- Use your shared Slack channel for time-sensitive POC questions. +- Email [support@mintlify.com](mailto:support@mintlify.com) for other questions. +- See [Advanced support](/advanced-support) for post-POC support options. ## After the POC - Everything to configure and verify before your documentation goes live for real. + Review everything to configure and verify before launch. From 37940fa328a3f4ae59a47f29c704a9595c864623 Mon Sep 17 00:00:00 2001 From: DeweyMarco Date: Tue, 25 Aug 2026 09:29:40 -0700 Subject: [PATCH 4/4] Apply review suggestions from @ethanpalm Make the step names in the intro workflow table and the section headings match exactly, and rename the participants table column to Role. Co-Authored-By: Claude Opus 5 (1M context) --- poc-onboarding.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/poc-onboarding.mdx b/poc-onboarding.mdx index ede7b4d6f..af110996d 100644 --- a/poc-onboarding.mdx +++ b/poc-onboarding.mdx @@ -23,7 +23,7 @@ Complete these steps in order: | 4. Publish a change | Verify your writing and review workflow. | | 5. Apply branding | Match the site to your product. | | 6. Test AI features | Evaluate assistant answers and one AI workflow. | -| 7. Review security | Confirm authentication and compliance requirements. | +| 7. Review IT and security requirements | Confirm authentication and compliance requirements. | | 8. Review results | Compare the POC against your success criteria. | Your repository remains the source of truth. The dashboard lets you edit, configure, and publish the `.mdx` files and `docs.json` configuration in that repository. Your live site displays the published result. @@ -32,7 +32,7 @@ Your repository remains the source of truth. The dashboard lets you edit, config ### Identify participants -| Participant | Responsibility | Time needed | +| Role | Responsibility | Time needed | |---|---|---| | Documentation owner | Runs the POC and completes most steps. | A few hours total | | GitHub administrator | Approves the Mintlify GitHub App. | 15 minutes | @@ -211,7 +211,7 @@ Ask a writer who does not use Git to complete this step. You can also test [preview deployments](/deploy/preview-deployments) for pull requests or [add the agent to Slack](/agent/slack#connect-your-slack-workspace) to propose documentation changes from Slack. -## Step 5: Apply your branding +## Step 5: Apply branding Update your brand settings in `docs.json`: @@ -330,7 +330,7 @@ Test with one account in the group and one account outside it. - Enable [CI checks](/deploy/ci) for links and accessibility. - Share [Enterprise contracting](/enterprise-contracting) with security and procurement teams. -## Step 8: Review the results +## Step 8: Review results Book one hour with your decision maker. Start with the goal and baseline you defined before the POC, then review: