发布与协作工具

文档写完还要 发布、协作、度量。工具链选型影响 Review 效率、多语言扩展与内容质量监控。

学习目标

• 了解 CMS、静态站点、Docs-as-Code 的适用场景
• 理解查重与链接健康检查的作用
• 建立 UTM 与文档 analytics 的基础用法

核心概念

发布形态对比

方案	优点	缺点
CMS（Notion、Contentful）	非工程可编辑	与代码示例易脱节
静态站点（Docusaurus、MkDocs）	Git 版本、预览快	需 CI 发布
内嵌 docs 仓	示例与 API 同源	权限与导航需设计

CodeRoadMap 类平台常见 Markdown 源 + CI 构建 + CDN；API Reference 可由 OpenAPI 生成。

协作与 Review

Draft — 作者分支或 CMS 草稿
Tech Review — 工程验证步骤与版本
Editorial Review — 风格、链接、 inclusive
Publish — 合并 + 缓存刷新 + 公告

Slack / Linear 工单与文档 PR 互链，避免 「文档改了没人知道」。

查重与质量

• 重复段落：合并为单页 + 链接，利于 SEO
• 链接检查：CI 跑 lychee、markdown-link-check
• ** Vale**：禁止词、被动语态阈值、术语一致性

链接追踪

https://coderoadmap.com/docs/quickstart?utm_source=newsletter&utm_medium=email&utm_campaign=launch

区分渠道效果；文档内 CTA 与 外链分享 分开标记。注意 GDPR / 隐私政策披露。

练习

• 对比 Docusaurus vs Notion 写你的团队选型理由（3 条）
• 设计文档 PR Checklist（至少 6 项）
• 为 Quickstart 页写 2 个 UTM 链接场景（邮件 vs Twitter）

小结

工具服务流程：Draft → Review → Publish → Measure；自动化检查省人工漏网。 下一课专讲 API 文档与 OpenAPI。