mintlify__docs/poc-onboarding.mdx

---
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
---

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.

<Note>
  If you get stuck, contact your account executive (AE) or solutions engineer (SE), or email [support@mintlify.com](mailto:support@mintlify.com).
</Note>

## POC workflow

Complete these steps in order:

| 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 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.

## Before you begin

### Identify participants

| 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 |
| Designer or brand owner | Provides logos, colors, and fonts. | 30 minutes |
| Identity or IT administrator | Configures DNS for a custom domain, if you test authentication. | 1 to 2 hours |

### Gather your content and brand assets

Collect:

- 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.

### Define success

Choose one of the value drivers that customers most commonly measure Mintlify against, then record its current baseline:

- **Acquisition:** Improve activation rate or time to first integration.
- **Deflection:** Reduce ticket volume for a common support topic.
- **Engineering time saved:** Reduce the engineering hours spent writing, reviewing, and maintaining documentation.
- **Retention:** Increase adoption of a feature after launch.

Add two or three criteria that you can test during the POC. For example:

- 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.

Share the goal, baseline, and criteria with your AE or SE.

## Step 1: Connect your repository

<Warning>
  A GitHub organization owner or repository administrator must approve the Mintlify GitHub App before your site can deploy.
</Warning>

<Steps>
  <Step title="Create your account">
    Go to [mintlify.com/start](https://mintlify.com/start) and sign up with your work email address.
  </Step>

  <Step title="Choose a repository">
    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 contains application code or unrelated files.
  </Step>

  <Step title="Install the GitHub App">
    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 requested permissions.

    <Accordion title="Request approval from an organization owner">
      If you cannot approve the app, submit the installation request. GitHub notifies your organization owners.

      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).
    </Accordion>
  </Step>

  <Step title="Open your site">
    After the starter content deploys, find your URL on the **Overview** page of the [dashboard](https://app.mintlify.com/). Open the `https://<your-subdomain>.mintlify.site` URL and confirm that it loads.
  </Step>
</Steps>

Use the `.mintlify.site` URL during the POC unless you need to test authentication. Authentication requires a [custom domain](/customize/custom-domain) or `*.mintlify.app` subdomain, and does not work on a custom basepath such as `yourcompany.com/docs`.

## Step 2: Invite your team

Open the [Members](https://app.mintlify.com/settings/organization/members) page and assign the narrowest role each participant needs:

- **Admin:** Manages organization settings, billing, and integrations.
- **Editor:** Creates and publishes content.
- **Viewer:** Reviews the dashboard and analytics without editing.

See [Roles](/dashboard/roles) for a complete permissions list.

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 if you test authentication.

## Step 3: Add sample content

### Choose representative pages

Start with your 20 to 30 highest-traffic pages. Include:

- Your most complex API reference page.
- A page with a large table or deeply nested list.
- A page with images, video, or diagrams.
- A page with custom components or embedded widgets.
- Two or three typical guides.

Keep the sample under 50 pages so you can focus on migration quality.

### Move the content

<Tabs>
  <Tab title="Use Mintlify migration services">
    Ask your AE or SE whether migration is included in your POC. If it is, send:

    - Your current documentation URL or export.
    - Your list of sample pages.
    - Your OpenAPI file or URL, if applicable.
    - Your brand assets.

    See [Enterprise migrations](/migration-services/enterprise) for the full migration process.
  </Tab>

  <Tab title="Migrate it yourself">
    Use one of these methods:

    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).

    See [Migrate to Mintlify](/migration) for other platforms.
  </Tab>

  <Tab title="Connect an existing content source">
    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).
  </Tab>
</Tabs>

### Review the migration

Compare each sample page with its source. Check:

- Images, tables, and code samples.
- Internal and external links.
- Custom components and embeds.
- Navigation labels and page placement.

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 AE or SE in one list with the page URL and expected result.

## Step 4: Publish a change

Ask a writer who does not use Git to complete this step.

<Steps>
  <Step title="Create a branch">
    Open the [web editor](https://app.mintlify.com/editor). Select the **Live site** dropdown, open the **Branches** tab, and select **New branch**.

    A branch keeps the draft separate from your deployed site.
  </Step>

  <Step title="Edit a page">
    Edit the page in the visual editor. Type `/` to insert a component or drag an image onto the page to upload it.

    Use the eye icon to preview the rendered page and the `</>` icon to view its MDX source.
  </Step>

  <Step title="Share the preview">
    Copy the branch preview URL and send it to a reviewer. Make any requested changes on the same branch.
  </Step>

  <Step title="Publish">
    Select **Publish**. Publishing from a branch opens or updates a pull request. Publishing from **Live site** deploys the change immediately.

    Confirm that the commit appears on the dashboard **Overview** page and that the approved change appears on your site.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Keep your existing review controls">
    Editor changes create Git commits, so CODEOWNERS, required reviews, and branch protection continue to apply.
  </Accordion>

  <Accordion title="Work in Markdown or locally">
    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.
  </Accordion>
</AccordionGroup>

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 branding

Update your brand settings in `docs.json`:

```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"
}
```

Then:

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.

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 AE or SE.

## Step 6: Test AI features

### Configure the assistant

Open the [Assistant](https://app.mintlify.com/products/assistant) page:

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.

See [Customize the assistant](/assistant/customize) and [Assistant skills](/assistant/skills) for product-specific instructions and tone.

### Test real questions

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.

Review unanswered and downvoted questions in [Assistant analytics](/analytics/assistant). If a relevant page is not cited, make its frontmatter `description` specific and unique.

### Test one additional AI workflow

Choose the workflow most relevant to your evaluation:

<AccordionGroup>
  <Accordion title="Embed the assistant">
    Add the [assistant widget](/assistant/widget) to your product, marketing site, or support portal.
  </Accordion>

  <Accordion title="Connect AI tools">
    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.

    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).
  </Accordion>

  <Accordion title="Automate a maintenance task">
    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).
  </Accordion>
</AccordionGroup>

## Step 7: Review results

Book one hour with your decision maker. Start with the goal and baseline you defined before the POC, then review:

| Criterion | Evidence |
|---|---|
| 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. |

Resolve open questions with your AE or SE before this meeting.

## Suggested timeline

Most POCs take two to three weeks:

| Week | Focus |
|---|---|
| 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 | Review the results with your decision maker. |

## Getting help

- Contact your AE or SE 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

<Card title="Go-live checklist" icon="file-check" horizontal href="/migration-services/go-live-checklist">
  Review everything to configure and verify before launch.
</Card>