文档工具怎么选？一个被 deadline 逼疯的微信小程序开发者的血泪经验

大家好，我是阿哲，在腾讯干了三年客户端开发，主要折腾微信小程序相关的业务。白天在工位上跟产品经理 battle 需求合理性，晚上回家刷 LeetCode 准备跳槽——没错，最近正在悄悄看机会，所以特别关注工程效率、代码质量和团队协作这些“软实力”。毕竟面试官一问“你们团队文档怎么管理的”，总不能说“全靠口口相传”吧？

上周五晚上，我又一次加班到十点，就为了改一个线上文档链接失效的问题。测试同学提了个 P0 级 Bug：“小程序帮助中心打不开，404”。我点进去一看，好家伙，文档地址是去年双11临时搭的静态页，部署在某个实习生名下的 COS bucket 上，人早就毕业了，bucket 也过期了。那一刻我真的想砸电脑。

但冷静下来一想：这哪是文档问题，这是流程和工具链的塌方。

于是，我花了周末两天时间，把我们团队的文档体系彻底重构了一遍。今天这篇，就是我的实战复盘——不讲大道理，只聊怎么用对工具，让文档真正“活”起来，而不是变成“数字骨灰盒”。

---

起因：为什么前端（尤其是 JS 项目）特别需要好文档？

可能有人会说：“我们写的是代码，又不是写书，要啥文档？”
但现实很打脸。微信小程序虽然逻辑层用的是 JavaScript，但涉及的模块特别碎：组件库、API 封装、埋点规范、CI/CD 流程、甚至和后端联调的字段约定……新人来了光靠看代码根本摸不清门道。

更别说 JS 本身动态性太强，类型信息缺失（除非你上 TS），函数参数到底传什么？回调怎么写？文档没写清楚，轻则浪费半天 debug 时间，重则线上出 bug 被老板 call 起来修。

我翻过公司内部的“技术债清单”，有将近 30% 的 issue 根源都是“文档缺失或过期”。而其中，JavaScript 项目的文档维护成本尤其高——因为迭代快、接口变、人员流动大。

所以，工具必须能解决三个核心问题：

1. 写得爽：支持 Markdown、代码块高亮、自动 API 提取
2. 看得爽：搜索快、结构清晰、响应式适配手机（毕竟小程序开发者经常在手机上看文档）
3. 活得久：能和代码仓库联动，CI 自动构建，避免“人走文档死”

---

我踩过的坑：从 Notion 到 GitBook 再到自建

一开始我们也图省事，直接用 Notion 搭了个文档空间。确实香：拖拽方便、实时协作、还能插表格画流程图。但问题很快就暴露了：

• 无法和代码同步：JS 工具函数改了参数，Notion 里的示例还是旧的
• 权限混乱：实习生也能删主文档，有一次误删了整个接入指南
• 搜索弱鸡：想找 wx.request 的封装说明，搜“请求”、“网络”、“API”都找不到

后来转战 GitBook，感觉专业多了。支持 Markdown、能导出 PDF、还有版本管理。但免费版限制太多，私有仓库要付费，而且构建速度慢得像蜗牛。每次 push 后等十几分钟才更新，开发体验极差。

最致命的是：它不支持从 JS 代码中自动提取注释生成文档。我们有个公共 utils 库，里面有 50+ 个函数，每个都要手动在 Gitbook 里写说明，谁愿意干这活？结果就是文档越积越旧，最后没人信了。

那段时间，团队士气低迷。新来的同事问我：“这个 formatTime 函数第二个参数是布尔还是字符串？” 我只能苦笑：“你去翻三个月前的 PR 吧。”

---

转机：用 Docusaurus + JSDoc 打造“活文档”

转折点出现在上个月参加深圳的一场前端分享会。有个字节的哥们提到他们用 Docusaurus + TypeDoc 做 TS 项目的文档自动化。我眼睛一亮——虽然我们还没全量上 TS，但 JS 也有 JSDoc 啊！

回家立马试水。核心思路就一条：让文档从代码里长出来，而不是另外写一遍。

第一步：规范 JSDoc 注释

先给团队定下规矩：所有公共函数、组件、类，必须写 JSDoc。比如：

/**
 * 格式化时间戳为 YYYY-MM-DD HH:mm
 * @param {number} timestamp - Unix 时间戳（毫秒）
 * @param {boolean} [showSeconds=false] - 是否显示秒
 * @returns {string} 格式化后的时间字符串
 * @example
 * formatTime(1672502400000); // "2023-01-01 00:00"
 * formatTime(1672502400000, true); // "2023-01-01 00:00:00"
 */
export function formatTime(timestamp, showSeconds = false) {
  // ...
}

看起来多写了点注释，但换来的是自动生成的 API 文档，值！

第二步：用 Docusaurus 搭建站点

Docusaurus 是 Facebook 开源的静态站点生成器，专为文档设计。优势很明显：

• 基于 React，支持 MDX（Markdown + JSX）
• 内置搜索（Algolia 免费额度够用）
• 主题可定制，移动端体验优秀
• 支持版本化（适合小程序 SDK 这种需要兼容多版本的场景）

初始化命令一行搞定：

npx create-docusaurus@latest my-docs classic

然后重点来了：集成 JSDoc 自动生成 API 页面。

我们写了个简单的脚本，在 docusaurus.config.js 里加了个 plugin：

// scripts/generate-api-docs.js
const jsdoc = require('jsdoc-api');
const fs = require('fs');

const docs = jsdoc.explainSync({
  files: ['../src/utils/*.js', '../src/components/*.js'],
  configure: './jsdoc.conf.json'
});

// 转成 Docusaurus 能读的 Markdown
docs.forEach(doc => {
  const md = `---
id: ${doc.name}
title: ${doc.name}
---

${doc.description || ''}

\`\`\`js
${doc.meta.code}
\`\`\`

#### 参数
${doc.params?.map(p => `- \`${p.name}\`: ${p.description}`).join('\n') || '无'}
`;
  fs.writeFileSync(`docs/api/${doc.name}.md`, md);
});

每次 npm run build 前跑一下这个脚本，API 文档就自动更新了。

---

效果对比：工具选对，效率翻倍

我把新旧方案做了个对比，数据说话：

维度	Notion / GitBook	Docusaurus + JSDoc
文档与代码一致性	❌ 手动维护，极易过期	✅ 自动生成，随代码提交更新
搜索体验	⚠️ 慢，关键词匹配弱	✅ Algolia 秒搜，支持 API 名称
新人上手成本	⚠️ 需额外学习文档结构	✅ 直接看代码注释 + 在线文档
移动端适配	⚠️ GitBook 还行，Notion 一般	✅ 响应式设计，小程序开发者友好
CI/CD 集成	❌ 几乎不可能	✅ GitHub Actions 自动部署
成本	💰 GitBook 私有库收费	💸 完全开源免费

最爽的是，现在我们把文档站点部署在公司的内网 CDN 上，URL 固定为 https://docs.myteam.tencent.com。再也不用担心实习生离职导致链接失效了！

---

附加工具链：让文档真正“活”起来

光有生成还不够，得让它融入日常开发流程。我们做了三件事：

1. PR 模板强制关联文档
   在 .github/PULL_REQUEST_TEMPLATE.md 里加了一行：

   - [ ] 本 PR 修改了公共 API，已更新 JSDoc 并确认文档生成正常
   

2. CI 卡点检查
   在 Jenkins 脚本里加了个步骤：如果修改了 src/utils 或 src/components，必须同时存在对应的 docs/api/*.md 更新，否则构建失败。

3. 文档即书籍：定期归档 PDF
   虽然在线文档是主力，但我们用 docusaurus-pdf 插件每月生成一份 PDF 存档，命名为《XX 小程序开发手册 v2023.08》。新同事入职时直接发 PDF，比口头培训靠谱多了。

说到“书籍”，其实我一直觉得，好的技术文档就应该像一本精心排版的书——有目录、有索引、有示例、有上下文。而不仅仅是零散的知识碎片。

---

给想跳槽的同学一点建议

最近刷题之余，我也在研究各家大厂的工程体系。发现一个规律：越是重视文档的团队，代码质量越高，协作越顺畅。

面试时被问到“你怎么保证代码可维护性”，如果你能掏出一套文档自动化方案，绝对加分。我上周面了一个二线厂，聊到文档工具链时，面试官眼睛都亮了：“你们真用 JSDoc 自动化？我们还在手动写 Confluence！”

所以别小看文档。它不仅是知识沉淀，更是工程素养的体现。

---

最后：工具是手段，人才是核心

当然，工具再好，也得有人用。我们团队现在有个“文档日”：每双周五下午，所有人停下手头需求，集中 review 文档、补注释、优化结构。

刚开始有人抱怨：“又不是写论文！” 但一个月后，大家发现 debug 时间少了，跨组沟通顺畅了，连产品经理都跑来夸：“你们的帮助中心终于能看了！”

所以啊，别等到线上 404 才想起文档的重要性。趁现在，花一天时间搭个 Docusaurus，规范下 JSDoc。未来某个加班的深夜，你会感谢今天的自己。

资源推荐（全是亲测好用）：

• Docusaurus 官方文档
• JSDoc 入门指南
• 书籍《Documenting APIs: A Guide for Technical Writers and Engineers》（虽然是英文，但理念超前）
• GitHub 搜索 docusaurus jsdoc example，有很多现成模板

好了，我要去刷下一道 LeetCode 了。希望下次跳槽时，能加入一个文档比代码还整洁的团队 😅