diff --git a/poc-onboarding.mdx b/poc-onboarding.mdx new file mode 100644 index 000000000..af110996d --- /dev/null +++ b/poc-onboarding.mdx @@ -0,0 +1,370 @@ +--- +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 Mintlify representative in your shared Slack channel 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 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. + +## 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 authentication and DNS, if required. | 1 to 2 hours | +| Decision maker | Reviews the POC against your success criteria. | 1 hour | + +### 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 business goal and record its current baseline: + +- **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. + +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 Mintlify representative. + +## 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. + + + 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). + + + + + 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 unless you need to test authentication. Authentication requires a custom domain or `*.mintlify.app` subdomain. + +## 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 during step 7. + +## 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 Mintlify representative 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 Mintlify representative 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). Select the **Live site** dropdown, open the **Branches** tab, and select **New 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. + + Use the eye icon to preview the rendered page and the `` icon to view its MDX source. + + + + Copy the branch preview URL and send it to a reviewer. Make any requested changes on the same branch. + + + + 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. + + + + + + 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](/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 Mintlify representative. + +## 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: + + + + 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 IT and security requirements + +Bring your IT or security team into the POC before the final review. + + + 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. + + +### Control dashboard access + +Evaluate the controls your team requires: + +- [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). + +### Control documentation access + +Configure [authentication](/deploy/authentication-setup) for your readers: + +- **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. + +Use [groups](/deploy/authentication-setup#control-access-with-groups) to restrict specific pages: + +```yaml +--- +title: "Production runbook" +groups: ["engineering"] +--- +``` + +Test with one account in the group and one account outside it. + + + `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). + + +### Complete infrastructure and compliance checks + +- 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 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. | +| Security requirements are met | Your IT team's review. | + +Resolve open questions with your Mintlify representative 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 | Complete the IT and security review, then review the results with your decision maker. | + +## Getting help + +- 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 + + + Review everything to configure and verify before launch. +