mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
70403b6014
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
363 lines
15 KiB
Plaintext
363 lines
15 KiB
Plaintext
---
|
||
title: "POC 入门指南"
|
||
description: "设置并评估 Mintlify 概念验证（POC），从连接仓库到审查发布、AI 和安全工作流。"
|
||
keywords: ["POC", "概念验证", "试用", "评估", "企业入门", "试点"]
|
||
noindex: true
|
||
---
|
||
|
||
使用本指南搭建一个可运行的文档站点，并与你的团队一起评估 Mintlify。大多数任务在控制面板中完成，但某些步骤需要 GitHub 和 IT 管理员的简短协助。
|
||
|
||
<Note>
|
||
如果遇到困难，请联系你的客户经理（AE，account executive）或解决方案工程师（SE，solutions engineer），或发送邮件至 [support@mintlify.com](mailto:support@mintlify.com)。
|
||
</Note>
|
||
|
||
<div id="poc-workflow">
|
||
## POC 工作流
|
||
</div>
|
||
|
||
请按顺序完成以下步骤：
|
||
|
||
| 步骤 | 成果 |
|
||
|---|---|
|
||
| 1. 连接你的仓库 | 部署一个入门站点。 |
|
||
| 2. 邀请你的团队 | 为参与者提供所需的访问权限。 |
|
||
| 3. 添加示例内容 | 测试具有代表性的复杂页面。 |
|
||
| 4. 发布一次更改 | 验证你的写作和审查工作流。 |
|
||
| 5. 应用品牌样式 | 让站点与你的产品保持一致。 |
|
||
| 6. 测试 AI 功能 | 评估助手的回答和一个 AI 工作流。 |
|
||
| 7. 审查结果 | 将 POC 与你的成功标准进行对比。 |
|
||
|
||
你的仓库始终是唯一数据源。控制面板让你可以编辑、配置和发布该仓库中的 `.mdx` 文件和 `docs.json` 配置。你的线上站点展示发布后的结果。
|
||
|
||
<div id="before-you-begin">
|
||
## 开始之前
|
||
</div>
|
||
|
||
<div id="identify-participants">
|
||
### 确定参与者
|
||
</div>
|
||
|
||
| 角色 | 职责 | 所需时间 |
|
||
|---|---|---|
|
||
| 文档负责人 | 主导 POC 并完成大部分步骤。 | 总计几个小时 |
|
||
| GitHub 管理员 | 批准 Mintlify GitHub 应用。 | 15 分钟 |
|
||
| 设计师或品牌负责人 | 提供徽标、颜色和字体。 | 30 分钟 |
|
||
| 身份或 IT 管理员 | 如果你要测试身份验证，为自定义域名配置 DNS。 | 1 到 2 小时 |
|
||
|
||
<div id="gather-your-content-and-brand-assets">
|
||
### 收集你的内容和品牌资产
|
||
</div>
|
||
|
||
请收集：
|
||
|
||
- SVG 或 PNG 格式的浅色和深色徽标版本。
|
||
- 一个网站图标（favicon），最好是 SVG 格式。
|
||
- 以十六进制值表示的品牌颜色。
|
||
- 字体文件或你的 Google Fonts 字体名称。
|
||
- 你当前文档的链接或内容导出文件。
|
||
- 你的 OpenAPI 文件或 URL（如果你需要为 API 编写文档）。
|
||
- 你流量最高的 20 到 30 个页面。
|
||
|
||
<div id="define-success">
|
||
### 定义成功标准
|
||
</div>
|
||
|
||
从客户最常用来衡量 Mintlify 的价值驱动因素中选择一个，并记录其当前基线：
|
||
|
||
- **获客：** 提高激活率或缩短首次集成所需时间。
|
||
- **工单转移：** 减少某个常见支持主题的工单数量。
|
||
- **节省工程时间：** 减少工程师在编写、审查和维护文档上花费的时间。
|
||
- **留存：** 提高某个功能发布后的采用率。
|
||
|
||
添加两到三条可以在 POC 期间测试的标准。例如：
|
||
|
||
- 一位没有 Git 经验的作者可以在无人协助的情况下发布更改。
|
||
- 你最复杂的 API 参考页面能正确渲染。
|
||
- 助手能正确回答 10 个常见支持问题中的 8 个，并引用正确的页面。
|
||
- 你的身份提供商支持控制面板登录。
|
||
|
||
将目标、基线和标准分享给你的 AE 或 SE。
|
||
|
||
<div id="step-1-connect-your-repository">
|
||
## 第 1 步：连接你的仓库
|
||
</div>
|
||
|
||
<Warning>
|
||
在你的站点部署之前，必须由 GitHub 组织所有者或仓库管理员批准 Mintlify GitHub 应用。
|
||
</Warning>
|
||
|
||
<Steps>
|
||
<Step title="创建你的账号">
|
||
前往 [mintlify.com/start](https://mintlify.com/start)，使用你的工作邮箱注册。
|
||
</Step>
|
||
|
||
<Step title="选择一个仓库">
|
||
在初始设置过程中连接 GitHub。在你的公司组织中创建一个仓库或选择一个空仓库。常见的做法是使用一个名为 `docs` 的私有仓库。
|
||
|
||
不要选择包含应用程序代码或无关文件的仓库。
|
||
</Step>
|
||
|
||
<Step title="安装 GitHub 应用">
|
||
请你的 GitHub 管理员安装 Mintlify GitHub 应用。通过选择 **Only select repositories** 授予对文档仓库的访问权限。
|
||
|
||
有关所请求的权限，请参阅[安装 GitHub 应用](/zh/deploy/github#install-the-github-app)。
|
||
|
||
<Accordion title="向组织所有者申请批准">
|
||
如果你无法批准该应用，请提交安装请求。GitHub 会通知你的组织所有者。
|
||
|
||
要在等待批准期间继续操作，可以在初始设置中跳过 Git 提供商。Mintlify 会创建一个私有仓库，你之后可以在 [Git 设置](https://app.mintlify.com/settings/deployment/git-settings)中迁移它。请参阅[克隆到你自己的仓库](/zh/deploy/github#clone-to-your-own-repository)。
|
||
</Accordion>
|
||
</Step>
|
||
|
||
<Step title="打开你的站点">
|
||
入门内容部署完成后，在[控制面板](https://app.mintlify.com/)的 **Overview** 页面找到你的 URL。打开 `https://<your-subdomain>.mintlify.site` URL 并确认它可以加载。
|
||
</Step>
|
||
</Steps>
|
||
|
||
除非你需要测试身份验证，否则在 POC 期间请使用 `.mintlify.site` URL。身份验证需要[自定义域名](/zh/customize/custom-domain)或 `*.mintlify.app` 子域名，并且在自定义基础路径（例如 `yourcompany.com/docs`）上不起作用。
|
||
|
||
<div id="step-2-invite-your-team">
|
||
## 第 2 步：邀请你的团队
|
||
</div>
|
||
|
||
打开[成员](https://app.mintlify.com/settings/organization/members)页面，为每位参与者分配其所需的最小角色：
|
||
|
||
- **Admin：** 管理组织设置、账单和集成。
|
||
- **Editor：** 创建和发布内容。
|
||
- **Viewer：** 查看控制面板和分析数据，但不能编辑。
|
||
|
||
完整的权限列表请参阅[角色](/zh/dashboard/roles)。
|
||
|
||
至少邀请一位不使用 Git 的作者、一位工程师和决策者。使用他们的工作邮箱，以便在第 7 步中将他们的账号连接到你的身份提供商。
|
||
|
||
<div id="step-3-add-sample-content">
|
||
## 第 3 步：添加示例内容
|
||
</div>
|
||
|
||
<div id="choose-representative-pages">
|
||
### 选择有代表性的页面
|
||
</div>
|
||
|
||
从你流量最高的 20 到 30 个页面开始。请包含：
|
||
|
||
- 你最复杂的 API 参考页面。
|
||
- 一个包含大型表格或深层嵌套列表的页面。
|
||
- 一个包含图片、视频或图表的页面。
|
||
- 一个包含自定义组件或嵌入式小组件的页面。
|
||
- 两到三篇典型的指南。
|
||
|
||
将示例控制在 50 页以内，以便你专注于迁移质量。
|
||
|
||
<div id="move-the-content">
|
||
### 迁移内容
|
||
</div>
|
||
|
||
<Tabs>
|
||
<Tab title="使用 Mintlify 迁移服务">
|
||
询问你的 AE 或 SE 迁移服务是否包含在你的 POC 中。如果包含，请发送：
|
||
|
||
- 你当前文档的 URL 或导出文件。
|
||
- 你的示例页面列表。
|
||
- 你的 OpenAPI 文件或 URL（如适用）。
|
||
- 你的品牌资产。
|
||
|
||
完整的迁移流程请参阅[企业迁移](/zh/migration-services/enterprise)。
|
||
</Tab>
|
||
|
||
<Tab title="自行迁移">
|
||
使用以下方法之一：
|
||
|
||
1. 从当前平台导出 Markdown。按照 [Docusaurus](/zh/migration/docusaurus)、[ReadMe](/zh/migration/readme)、[GitBook](/zh/migration/gitbook)、[Fern](/zh/migration/fern) 或 [Document360](/zh/migration/document360) 的迁移指南操作。
|
||
2. 将少量页面粘贴到网页编辑器中并清理格式。
|
||
3. 使用 AI 工具结合 Mintlify [skill](/zh/ai/skillmd) 和[管理 MCP 服务器](/zh/ai/mintlify-mcp)转换内容。
|
||
|
||
其他平台请参阅[迁移到 Mintlify](/zh/migration)。
|
||
</Tab>
|
||
|
||
<Tab title="连接现有内容源">
|
||
如果你的源内容位于 Notion、Confluence、Jira 或类似工具中，请将其连接到 Mintlify 代理。请参阅[代理和自动化的集成](/zh/automations/integrations)。
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
<div id="review-the-migration">
|
||
### 审查迁移结果
|
||
</div>
|
||
|
||
将每个示例页面与其源页面进行对比。检查：
|
||
|
||
- 图片、表格和代码示例。
|
||
- 内部和外部链接。
|
||
- 自定义组件和嵌入内容。
|
||
- 导航标签和页面位置。
|
||
|
||
确认新用户能在两次点击内到达有用的页面，并且导航标签使用读者可能搜索的术语。将迁移问题整理成一份列表（包含页面 URL 和预期结果）发送给你的 AE 或 SE。
|
||
|
||
<div id="step-4-publish-a-change">
|
||
## 第 4 步：发布一次更改
|
||
</div>
|
||
|
||
请一位不使用 Git 的作者完成此步骤。
|
||
|
||
<Steps>
|
||
<Step title="创建分支">
|
||
打开[网页编辑器](https://app.mintlify.com/editor)。选择 **Live site** 下拉菜单，打开 **Branches** 标签页，然后选择 **New branch**。
|
||
|
||
分支可以将草稿与已部署的站点分开。
|
||
</Step>
|
||
|
||
<Step title="编辑页面">
|
||
在可视化编辑器中编辑页面。输入 `/` 插入组件，或将图片拖到页面上进行上传。
|
||
|
||
使用眼睛图标预览渲染后的页面，使用 `</>` 图标查看其 MDX 源码。
|
||
</Step>
|
||
|
||
<Step title="分享预览">
|
||
复制分支预览 URL 并发送给审阅者。在同一分支上完成所有被要求的修改。
|
||
</Step>
|
||
|
||
<Step title="发布">
|
||
选择 **Publish**。从分支发布会打开或更新一个拉取请求。从 **Live site** 发布会立即部署更改。
|
||
|
||
确认提交出现在控制面板的 **Overview** 页面上，并且已批准的更改出现在你的站点上。
|
||
</Step>
|
||
</Steps>
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="保留你现有的审查控制">
|
||
编辑器的更改会创建 Git 提交，因此 CODEOWNERS、必需审查和分支保护会继续生效。
|
||
</Accordion>
|
||
|
||
<Accordion title="在 Markdown 中或本地工作">
|
||
作者可以继续使用编辑器的 Markdown 视图。工程师可以安装 [CLI](/zh/cli/install)，克隆仓库，并在本地运行 [`mint dev`](/zh/cli/preview)。
|
||
</Accordion>
|
||
</AccordionGroup>
|
||
|
||
你还可以测试拉取请求的[预览部署](/zh/deploy/preview-deployments)，或[将代理添加到 Slack](/zh/agent/slack#connect-your-slack-workspace)，直接在 Slack 中提出文档更改建议。
|
||
|
||
<div id="step-5-apply-branding">
|
||
## 第 5 步：应用品牌样式
|
||
</div>
|
||
|
||
在 `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"
|
||
}
|
||
```
|
||
|
||
然后：
|
||
|
||
1. 检查链接和按钮在浅色和深色模式下是否清晰可读。
|
||
2. 使用[字体设置](/zh/customize/fonts)添加你的字体。
|
||
3. 添加默认的 Open Graph 图片，并在 Slack 中测试分享链接的效果。
|
||
|
||
其他选项请参阅[外观设置](/zh/organize/settings-appearance)、[主题](/zh/customize/themes)和 [SEO](/zh/optimize/seo)。如果你不想编辑 `docs.json`，请将资产发送给你的 AE 或 SE。
|
||
|
||
<div id="step-6-test-ai-features">
|
||
## 第 6 步：测试 AI 功能
|
||
</div>
|
||
|
||
<div id="configure-the-assistant">
|
||
### 配置助手
|
||
</div>
|
||
|
||
打开[助手](https://app.mintlify.com/products/assistant)页面：
|
||
|
||
1. 启用助手。
|
||
2. 为需要人工协助的问题添加[转接电子邮件](/zh/assistant/configure#set-deflection-emails)。
|
||
3. 添加最多三个[起始问题](/zh/assistant/configure#add-sample-questions)。
|
||
4. 如果相关内容分布在多个站点上，请添加[搜索域名](/zh/assistant/configure#search-domains)。
|
||
5. 保持[机器人防护](/zh/assistant/configure#bot-protection)处于启用状态。
|
||
|
||
有关产品专属说明和语气，请参阅[自定义助手](/zh/assistant/customize)和[助手技能](/zh/assistant/skills)。
|
||
|
||
<div id="test-real-questions">
|
||
### 测试真实问题
|
||
</div>
|
||
|
||
1. 从支持工单或社区渠道收集 20 到 30 个近期问题。
|
||
2. 通过站点上的 **Ask Assistant** 逐个提问。
|
||
3. 记录回答是否正确以及是否引用了正确的页面。
|
||
4. 利用错误或缺失的回答来确定需要更新或创建的页面。
|
||
|
||
在[助手分析](/zh/analytics/assistant)中审查未回答和被点踩的问题。如果相关页面未被引用，请让其 frontmatter `description` 更加具体和独特。
|
||
|
||
<div id="test-one-additional-ai-workflow">
|
||
### 测试一个额外的 AI 工作流
|
||
</div>
|
||
|
||
选择与你的评估最相关的工作流：
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="嵌入助手">
|
||
将[助手组件](/zh/assistant/widget)添加到你的产品、营销网站或支持门户。
|
||
</Accordion>
|
||
|
||
<Accordion title="连接 AI 工具">
|
||
使用[搜索 MCP 服务器](/zh/ai/model-context-protocol)让已发布的内容可在受支持的 AI 工具中使用。使用[管理 MCP 服务器](/zh/ai/mintlify-mcp)起草和编辑文档。
|
||
|
||
你还可以测试[上下文菜单](/zh/ai/contextual-menu)、[`llms.txt`](/zh/ai/llmstxt)、[`skill.md`](/zh/ai/skillmd) 和 [Markdown 页面导出](/zh/ai/markdown-export)。
|
||
</Accordion>
|
||
|
||
<Accordion title="自动化一项维护任务">
|
||
启用一个[自动化](/zh/automations)，例如起草更新日志或在代码更改后更新文档。先从 **Require review** 开始，然后检查其提出的拉取请求和运行历史。请参阅[管理自动化](/zh/automations/manage)。
|
||
</Accordion>
|
||
</AccordionGroup>
|
||
|
||
<div id="step-7-review-results">
|
||
## 第 7 步：审查结果
|
||
</div>
|
||
|
||
与决策者预约一小时的会议。从 POC 前定义的目标和基线开始，然后审查：
|
||
|
||
| 标准 | 证据 |
|
||
|---|---|
|
||
| 非开发人员可以发布内容 | 第 4 步的结果和所需时间。 |
|
||
| 工程师保留审查控制权 | 拉取请求及其检查。 |
|
||
| 复杂内容迁移正确 | 示例页面的并排对比。 |
|
||
| 助手回答准确 | 你评分过的问题和引用的页面。 |
|
||
| 可以识别内容缺口 | [助手分析](/zh/analytics/assistant)中未回答和被点踩的问题。 |
|
||
| 读者能找到有用的内容 | [流量](/zh/analytics/traffic)、[搜索](/zh/analytics/search)和[用户参与](/zh/analytics/user-engagements)数据。 |
|
||
| 自动更新有价值 | 自动化的运行历史和提出的更改。 |
|
||
|
||
在此会议之前，与你的 AE 或 SE 解决所有未决问题。
|
||
|
||
<div id="suggested-timeline">
|
||
## 建议时间表
|
||
</div>
|
||
|
||
大多数 POC 需要两到三周：
|
||
|
||
| 周 | 重点 |
|
||
|---|---|
|
||
| 第 1 周 | 连接仓库、邀请团队、定义成功标准并开始内容迁移。如果需要身份验证，开始域名设置。 |
|
||
| 第 2 周 | 审查内容、发布一次更改、应用品牌样式、测试助手并评估一个 AI 工作流。 |
|
||
| 第 3 周 | 与决策者一起审查结果。 |
|
||
|
||
<div id="getting-help">
|
||
## 获取帮助
|
||
</div>
|
||
|
||
- 如有紧急的 POC 问题，请联系你的 AE 或 SE。
|
||
- 其他问题请发送邮件至 [support@mintlify.com](mailto:support@mintlify.com)。
|
||
- POC 之后的支持选项请参阅[高级支持](/zh/advanced-support)。
|
||
|
||
<div id="after-the-poc">
|
||
## POC 之后
|
||
</div>
|
||
|
||
<Card title="上线检查清单" icon="file-check" horizontal href="/zh/migration-services/go-live-checklist">
|
||
审查上线前需要配置和验证的所有内容。
|
||
</Card>
|