Skip to content

poc-onboarding.mdx

Latest commit

 

History

History
320 lines (226 loc) · 14.3 KB

poc-onboarding.mdx

File metadata and controls

320 lines (226 loc) · 14.3 KB
Raw
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.

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

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 Connects your identity provider, if you test authentication. Configures DNS if you also set up a custom domain. 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

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 sign up with your work email address. 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.
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>
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 during the POC. Authentication works on your .mintlify.site subdomain or a custom domain, but does not work on a custom subpath such as yourcompany.com/docs.

Step 2: Invite your team

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

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

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.

Open the [web editor](https://app.mintlify.com/editor). Click the branch name in the editor toolbar, select **Create new branch**, enter a name, then click **Create branch**. 
A branch keeps the draft separate from your deployed site.
Edit the page in the visual editor. Type `/` to insert a component or drag an image onto the page to upload it. 
Press <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd> (macOS) or <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd> (Windows) to switch between the rendered visual mode and the MDX source.
Select **Create pull request**. Mintlify builds a [preview deployment](/editor/review#preview-deployments): a temporary URL where your changes render exactly as they look when published. Copy the URL and send it to a reviewer. Make any requested changes on the same branch. The preview rebuilds each time you save. Merge the pull request to deploy the change to your live site. Publishing from your deployment branch deploys the change immediately without a pull request. See [Publish changes](/editor/publish). 
Confirm that the commit appears on the dashboard **Overview** page and that the approved change appears on your site.
Editor changes create Git commits, so CODEOWNERS, required reviews, and branch protection continue to apply. 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.

You can also test preview deployments for pull requests or add the agent to Slack to propose documentation changes from Slack.

Step 5: Apply branding

Update your brand settings in 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.
  3. Add a default Open Graph image and test a shared link in Slack.

See Appearance settings, Themes, and 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 page:

  1. Turn on the assistant.
  2. Add deflection email addresses for questions that need human help.
  3. Add up to three starter questions.
  4. Add search domains if relevant content spans multiple sites.
  5. Leave bot protection enabled.

See Customize the assistant and 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. 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:

Add the [assistant widget](/assistant/widget) to your product, marketing site, or support portal. 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).
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: 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.
Readers find useful content Traffic, search, and engagement 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 authentication setup if you plan to test it.
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

After the POC

Review everything to configure and verify before launch.