文档即代码 vs 可发布企业 Wiki：产品手册治理对照清单
文档即代码与可发布企业 Wiki 的对照，是把产品手册的源文件、审定门禁、发布面与阅读权限分开验收的判断标准。前者用 Git 与拉取请求控制上线；后者把已审定知识按站点权限交到内部门户或对外手册。
浏览 4
巴克励步
导语：先分清源文件、审定版本和发布面
文档即代码与可发布企业 Wiki 的对照，是把产品手册的「源文件放在哪里、谁来审、怎样才算已经发布、谁能在哪个站点读到」分开验收的一组判断标准。文档即代码把 Markdown 或 MDX 放进 Git 仓库，用拉取请求、分支保护和持续集成来控制上线；可发布企业 Wiki 则把已经审定的知识，按站点权限交付到内部门户、帮助中心或对外手册，而不是停在「编辑器里能看见最新稿」。
这和替代 Confluence / 语雀 / 飞书知识库的选型对照不是同一篇文章。那一篇解决的是协作 Wiki 与可发布 Wiki 的产品分界，以及该不该离开原系统；本文假定手册已经要对外交付，要回答的是：写作和发布该不该完全绑在 Git 工作流上。它也和产品手册与 Docs AI 可见性、内容治理不同：前者讨论发布之后的抓取、
llms.txt 与生成式引擎优化，后者讨论责任人、过期策略和新鲜度；本文讨论的是更靠前的一环——源文件与发布面如何分开、又如何对齐。产品定位见支柱文 Baklib Wiki 是什么。立项里最常见的误会有三个：一是把「工程师已经习惯在仓库里写文档」当成全公司手册的唯一治理模型；二是以为只要接上双向 Git 同步，Wiki 里的草稿、评论和未审定段落就会自动变成可按权限发布的正式版本；三是在 Git 仓库和协作 Wiki 里各维护一份几乎相同的手册，上线后很快分叉。对照的目的不是给某一类工具打分，而是先写清你要保住的门禁，再决定哪些内容走代码审查，哪些内容走站点发布。
为什么现在要谈：手册不再只写给「会开拉取请求的人」
第一，面向开发者的文档平台，已经把 Git 仓库写成默认的内容源。Mintlify 的概念说明写明：文档站点由仓库中的
.mdx 页面和必需的 docs.json 配置构建而成；浏览器编辑器、本地开发和在 Slack 中调用的代理，都会更新同一座仓库。部署分支上的发布可以触发正式站点构建，功能分支上的发布则可以写入分支或打开拉取请求，并为该请求提供临时预览地址。未写入 docs.json 导航的页面不会出现在站点目录里，但仍可能通过直接链接打开。见 Mintlify Concepts。第二，非工程角色并没有消失，平台自己也在补浏览器编辑和双向同步。GitBook 把 Git Sync 写成 GitHub 或 GitLab 仓库与文档站点之间的双向集成：开发者可以在仓库里提交 Markdown，技术写作者、教学设计师和产品经理可以在 GitBook 编辑器里修改、讨论并反馈；在 GitBook 中合并变更请求会向仓库提交，仓库中的提交也会同步回 GitBook。初始同步还要选择方向，官方明确提醒：若选择 GitHub → GitBook，选定分支的内容会替换对应分区，仓库为空或落后于尚未导出的变更请求时，这些内容会从分区和已发布站点中丢失。见 GitHub & GitLab Sync、Enabling GitHub Sync。
第三，产品手册往往同时包含两类内容。一类随接口、SDK、命令行和版本发布一起变化，适合和代码走同一条审查路径；另一类是安装说明、故障排查、政策条款、渠道手册和内部操作规范，贡献者更多是产品、支持、法务和实施人员，他们要的是按站点发布、按权限阅读，而不一定是向代码仓库提交。Mintlify 自己在解释「什么是文档即代码」时也划了这条边界：它更适合随产品变化的文档、API 参考、SDK 指南和内部工程文档；人事政策、销售材料和活动页，通常仍应放在这些团队已经在用的工具里。见 What is docs-as-code?。
把这三条放在一起，选型问题就从「要不要上文档即代码」变成：哪些手册必须与代码同审、同发，哪些手册必须按站点权限发布；以及，有没有一个发布面，能避免为了迁就某一种编辑习惯，而把全部知识塞进同一个仓库，或复制成两份逐渐过期的正文。
四个容易混在一起的词
在短名单上先把下面四个词拆开写。混用它们，最后往往得到「仓库里有最新 Markdown」或「Wiki 里刚保存过」，对外手册或 AI 检索用的却仍是另一份未审定、未授权的稿。
| 概念 | 它真正回答的问题 | 典型落地方式 |
|---|---|---|
| 源文件 | 现行正文以哪一份可版本化的文件或页面为准 | Git 仓库中的 Markdown / MDX，或知识库里的现行文档，而不是聊天记录和私人副本 |
| 审定版本 | 谁批准之后，才允许进入正式阅读面 | 受保护分支上的合并、知识库审核通过，或变更请求被指定审查人接受 |
| 发布面 | 读者实际打开的是哪一个站点、哪一组导航和哪一个 URL | 文档平台的生产部署，或知识库同步到已绑定的 Wiki 应用之后形成的前台 |
| 阅读权限 | 不同身份在该发布面上能看到什么 | 文档站点的认证与分组，或 Wiki 应用上的公开、登录可见、指定权限可见 |
一个可操作的判断句是：先画清「源文件 / 审定版本 / 发布面 / 阅读权限」四行，再看工具提供的是仓库同步、页面编辑，还是站点发布。 能在编辑器里改字，只覆盖了第一行里的写作动作。
还要把「仓库权限」和「站点阅读权限」分开。能向文档仓库推送的人，不等于应该在生产文档站上看到未发布接口；能打开内部门户的人，也不等于应该匿名访问对外手册。这与权限模型是同一条线，只是本文把它用在产品手册的发布路径上。
文档即代码真正提供的门禁
文档即代码的核心，不是「用 Markdown 写作」，而是把文档变更放进与代码相近的强制门禁里。Mintlify 把这一工作流概括为：在分支上编辑文件，打开拉取请求，由同事审查 diff，持续集成检查站点能否构建、内部链接是否指向真实页面，通过后再合并并自动发布。见 What is docs-as-code?。
这些门禁之所以可强制，通常要靠 Git 托管平台的分支保护，而不是只靠约定。GitHub 写明：可以为重要分支设置保护规则，默认禁止强制推送和删除该分支；还可以要求合并前必须通过指定数量的拉取请求审查、必须通过状态检查，以及限制谁能向匹配分支推送。管理员或具有「绕过分支保护」权限的自定义角色，默认不受这些限制，但规则也可以选择把限制同样施加到他们身上。需要审查时，协作者只能通过已获得足够批准的拉取请求向受保护分支推送。见 About protected branches。
责任人也可以写进仓库，而不是只写在文档页脚。GitHub 的 Code Owners 允许在保护规则中要求：任何影响某段代码（或某组路径）的拉取请求，必须先得到对应代码所有者的批准，才能合并进受保护分支。见 About code owners。对产品手册来说，这意味着 API 参考可以由接口所有者审查，故障排查可以由支持负责人审查，前提是这些路径被写进
CODEOWNERS，并且保护规则确实打开了「要求代码所有者审查」。持续集成则把「看起来写完了」和「构建与链接仍然成立」分开。Mintlify 的安装文档给出了一份 GitHub Actions 示例：在涉及
*.mdx 或 docs.json 的拉取请求上安装 CLI，先运行 mint format 并检查是否产生未提交差异，再运行 mint validate；校验若报告错误会以退出码 1 失败。概念说明还建议在发布前本地运行 mint validate 和 mint broken-links。见 Install the CLI、Mintlify Concepts。自托管的静态文档生成器走的是同一类门禁，只是基础设施要自己维护。Docusaurus 把自己定位为面向文档站点的静态站点生成器：用 Markdown / MDX 写作，支持版本管理、多语言、搜索和主题定制，并可发布到 GitHub Pages、Netlify、Vercel 等。它把「无厂商锁定」写成设计原则之一，同时也写明：要获得这些能力，需要团队自行承担站点构建、插件、主题和部署管线。见 Docusaurus Introduction。选择这条路时，验收的不只是「会写 Markdown」，还有谁负责升级生成器、谁保证预览环境和生产环境一致。
文档即代码适合的，是必须与产品变更对齐的那部分手册。接口新增字段、SDK 方法改名、命令行参数调整时，文档可以和代码出现在同一次审查里，回滚也有提交记录可依。它不自动解决的是：不会使用 Git 的贡献者如何参与、仓库权限如何映射到对外站点的阅读范围，以及同一份已审定知识如何在内网预览站和生产手册上按不同规则交付。浏览器编辑器和双向同步可以降低前一个问题的门槛，但不会取消后两个问题。
可发布企业 Wiki 真正提供的门禁
可发布企业 Wiki 的核心，也不是「页面好不好看」，而是把「写入内容源」和「出现在某个站点的阅读面」分成两步，并允许同一份已审定知识绑定到多个应用站点。Baklib 的产品说明写明：知识库只有通过绑定应用站点，才具有对外输出的 URL；内容分发查看的是当前文档在各站点的输出引用，而不是只开一个临时公开链接。见 知识库发布。
操作手册把步骤写得很具体。在知识库编辑器里点击「保存」，或等待自动保存成功，只是把文章写入内容源，此时前台 Wiki 并不必然更新。要进入「应用发布」，对已绑定的 Wiki 应用点击「立即同步」，变更才会推到该应用的数据源，并在前台访问中可见。一篇知识库可以绑定多个 Wiki 应用，例如中文站、英文站或内网预览站；每个应用卡片会显示最近同步时间，知识库已更新但尚未推送时会提示「数据已过期」。未同步的草稿不会到公开 Wiki，但成员在知识库里能看见的范围，仍受知识库权限约束。见 发布到 Wiki 应用站点、知识库分发与导出。
这套门禁解决的是另一类真实问题。产品经理修改安装说明、支持人员更正故障排查、实施顾问更新项目交付手册时，他们需要的是可预览、可按站点同步、可按身份阅读，而不一定是向代码仓库提交。内网预览站可以先同步、先验证，生产手册再同步；公开站点、登录可见站点和指定权限可见站点，也可以共用同一份已审定正文，却使用不同的访问规则。导出则把整库或子树变成 Markdown、JSON / CSV、Word 或 PDF，用于备份和下游对接，而不是把发布面锁死在单一厂商的编辑器里。见 知识库分发与导出。
它不自动提供的，是 Git 那种与代码变更绑定的强制合并规则和构建检查。如果你的 API 参考必须和发行分支同时上线，单靠 Wiki 页面的「已保存」或「已同步」还不够，还要把这份手册与发布节奏对齐，或让工程文档继续留在仓库里，由发布面引用已审定的结果。可发布 Wiki 擅长的是把已经审定的知识，按站点交付出去；文档即代码擅长的是让随代码变化的段落，无法绕过审查和检查就进入生产分支。
对照表：把治理手段逐项对齐，而不是比谁更「现代」
下面这张表不是功能打分，而是把两类工作流里名字不同、问题相近的手段对齐，便于写进产品手册的治理方案。
| 治理问题 | 文档即代码中的典型手段 | 可发布企业 Wiki 中的典型手段 | 验收时要看到什么 |
|---|---|---|---|
| 源文件以哪一份为准 | 仓库中的 Markdown / MDX 与 docs.json 或等价配置 |
知识库中的现行文档，而不是各站点各自复制的正文 | 能指出唯一现行源；找不到第二份长期分叉的「正式稿」 |
| 谁有权改，谁必须审 | 仓库写权限、CODEOWNERS、要求审查后才能合并 | 知识库角色、页面或目录责任人、发布前审核 | 关键路径上的变更能被对应所有者拦住，而不是任何人保存即生效 |
| 怎样防止未审定内容进入生产 | 分支保护、必过状态检查、预览部署 | 保存不等于同步；按应用分别发布；草稿不进入公开站点 | 生产阅读面只出现已审定版本；预览环境可以单独验证 |
| 导航与正文是否同一回事 | 页面文件存在，不等于已写入导航配置 | 知识库目录存在，不等于已同步到某应用的前台 | 目录、隐藏页和直接链接的行为与预期一致 |
| 多站点如何避免分叉 | 多项目或多仓库，或同一仓库的不同部署分支 / 目录 | 同一知识库绑定多个 Wiki 应用，分别同步 | 中文站、英文站、内网预览和生产手册引用同一份已审定源，而不是互相粘贴 |
| 历史与回滚 | 提交记录、拉取请求和标签 / 发行版本 | 页面历史、同步记录和导出备份 | 能回答「上一版正式手册说了什么」，并能在出错后回到上一审定版本 |
| 阅读权限 | 文档站点的认证、分组和私有化部署 | 应用站点上的公开、登录可见或指定权限可见 | 用真实身份抽查：不该看见的人打不开，该看见的人能打开现行版本 |
| 与代码发布对齐 | 同一拉取请求或同一发行分支审查文档与代码 | 按产品版本维护手册，并在发布窗口同步对应站点 | 接口变更上线时，对外手册不是仍指向旧参数 |
对照时有两个容易忽略的限制。其一，Git 托管平台的保护能力与套餐、仓库可见性有关。GitHub 写明：受保护分支适用于使用 GitHub Free 的公共仓库，以及使用 Pro、Team、Enterprise Cloud 或 Enterprise Server 的公共和私有仓库。见 About protected branches。若手册仓库是私有的，又没有相应套餐，口头约定的「必须走拉取请求」可能并没有被平台强制。其二，双向同步会改变「哪一边才是源」。GitBook 要求每次启用或重建 Git Sync 都确认仓库、分支和方向；选错方向可能用旧仓库覆盖编辑器里尚未导出的变更。见 Enabling GitHub Sync。这两条都说明：工具开关打开了，不等于治理已经生效。
五种不该直接套用的做法
不要把「全公司知识进同一个 docs 仓库」当成文档即代码的完成态。仓库权限通常按工程组织切分，很难同时表达「实施顾问可改交付手册、但不能看未发布路线图」「法务必须审查条款页」「合作伙伴只能读指定站点」。Mintlify 已经建议：不随产品变化的人事、销售和活动内容，不必迁进文档仓库。见 What is docs-as-code?。更稳妥的分拣是：随代码变化的参考文档进仓库；要对不同读者按站点交付的手册和制度，进可发布知识库。
不要把「已经能在 Wiki 里嵌入或同步 Git 文件」当成发布治理已经完成。市场里确有把仓库中的 Markdown 发布或嵌入 Confluence 的应用与开源工具，例如把 Git 文件渲染进页面，或由持续集成把文档树写成 Wiki 页面。这类集成解决的是「工程师写在仓库里，其他人在 Wiki 里读得到」，并不自动等于：生产手册只包含已审定版本、对外站点与内部门户使用不同权限、草稿和评论不会进入公开检索。若目的地仍是协作 Wiki 的「写完即可见」，可发布企业 Wiki 的选型对照里讨论的产品分界就还在。
不要靠复制粘贴维持「仓库版」和「Wiki 版」两份正式稿。短时间内看起来都在更新，发行后第二周就会出现一边已修正参数、另一边的支持人员和对外助手仍在引用旧段落。要么让仓库成为工程参考的唯一源，发布面只引用构建结果；要么让可发布知识库成为对客手册和内部制度的唯一源，工程仓库只保留与代码强绑定的参考，并在发布说明里互相链接。不要让两份正文同时对读者自称「现行版本」。
不要假设浏览器编辑器已经取消了 Git 门禁。若编辑器可以在部署分支上直接发布，而分支保护又允许管理员绕过审查，手册仍可能不经拉取请求就上线。正确的验收是：看生产分支是否强制要求审查和状态检查，看编辑器在功能分支上是否只会打开拉取请求，以及管理员绕过是否被关闭或被审计。工具宣传「也可以在浏览器里写」，不等于生产发布已经被保护。
不要把构建通过当成阅读权限已经正确。文档站点成功部署，只说明源文件可以生成页面；谁能打开这些页面，要另做认证和授权抽查。可发布 Wiki 也一样：同步成功只说明应用数据源已更新，还要用匿名、登录用户和指定角色各走一遍关键路径。权限抽查的方法见权限模型；本文只要求：发布验收里必须包含阅读权限，而不是只看构建日志或同步时间。
可执行核对清单：把手册治理写进方案，而不是写进口号
下面十问可以直接贴进产品手册或文档平台的立项书。对每一问，要求看到仓库规则、发布记录或站点抽查，而不是只看一次「我们用了文档即代码」或「我们已经有 Wiki」的口头说明。
- 有没有把内容分成「随代码变化的参考」和「按站点交付的手册 / 制度」？ 两类内容可以交叉引用，但不应强行共用同一套仓库权限或同一套「保存即可见」规则。
- 源文件、审定版本、发布面和阅读权限是否写成四行，而不是混成一句「文档已经上线」？ 能指出每一行的系统、责任人和验收动作。
- 随代码变化的文档，是否走受保护分支上的拉取请求，并且审查和状态检查是强制的？ 要核对接入套餐是否真的提供分支保护，管理员绕过是否被限制，CODEOWNERS 是否覆盖关键路径。
- 构建、链接和格式检查是否在合并前自动运行，失败时能否挡住发布？ 例如在文档拉取请求中运行校验和断链检查，而不是发布后靠读者报错。
- 非工程贡献者是通过带门禁的浏览器编辑器参与，还是被要求直接操作 Git，或退回离线文稿？ 若使用双向同步，初始方向、冲突处理和预览方式是否写明，并且不会用空仓库覆盖已有文稿。
- 「文件已存在」和「已出现在正式导航 / 正式站点」是否分开验收？ 未纳入导航的隐藏页、仅能通过直接链接打开的页，不应被当成已对目标读者发布。
- 对客手册、内网预览和内部制度是否引用同一份已审定源，并分别同步到不同站点？ 若仍靠复制粘贴维持多份正式稿，应视为治理未完成。
- 保存、同步或部署之后，是否用匿名、登录用户和指定角色抽查过阅读范围？ 既要避免未发布内容泄露，也要避免授权用户打不开现行版本。
- 发行窗口里，接口或功能变更是否与对应手册更新绑定？ 不能绑定时，要有明确的延期发布、警告横幅或回滚条件，而不是默认「代码先上、文档后补」。
- 现行知识在进入检索和问答之前，是否只使用对应发布面中已审定、已授权的版本？ 草稿、评论、已过期页和仅内网可见的段落，不应和对外手册混用同一份未过滤索引。Baklib 将知识资产发布、权限交付与一源多站写成同一条产品逻辑：一份内容可以输出到不同应用站点，并分别设置公开、登录可见或指定权限可见。见 知识库发布、Baklib Wiki。
怎么选：先画内容边界，再挑工作流
先不要从「哪家更像开发者工具」或「哪家编辑器更好看」开始。先列出手册里真正随代码变化的部分，以及必须按站点、按身份交付的部分。前者优先采用文档即代码：仓库作为源文件，拉取请求和持续集成作为审定门禁，生产部署作为发布面。后者优先采用可发布企业 Wiki：知识库作为源文件，审核和按应用同步作为审定与发布门禁，不同 Wiki 站点作为带权限的阅读面。
如果团队已经在 Mintlify、GitBook 或自托管的 Docusaurus / MkDocs 上运行开发者文档，不必为了「统一工具」把支持手册和内部制度全部迁进同一个仓库。更常见、也更不容易分叉的做法是：让工程参考继续留在仓库里，把要对不同读者交付的手册放到可发布知识库，并在两边只保留必要的交叉链接。发布后的抓取、
llms.txt 和助手可见性，再按Docs AI 可见性清单验收；那是发布面稳定之后的下一步，不是选择工作流时的第一问。对既要与代码同发、又要对客和内部按权限交付的团队，目标不应停在「仓库能构建」或「Wiki 能保存」。更完整的结果是：每类知识都有唯一的源文件和明确的审定门禁，已发布版本按站点交付，检索和问答只使用对应发布面的内容。Baklib Wiki 适合在需要按站点发布、按权限阅读、并避免多份正式稿分叉时介入：它不是把 Git 的分支保护原样搬进页面编辑器，而是把已经审定的知识变成可发布、可设权、可按应用同步的资产。见 Baklib Wiki、知识库发布。
若你正从协作 Wiki 迁出，并计划把一部分文档改成仓库工作流、另一部分改成可发布知识库，迁入时仍要按迁移对照清单分层验收权限、附件、宏和历史，不要假定「改用 Markdown 仓库」就自动完成了搬迁。
参考来源
想要了解更多?
数字内容新基建白皮书
常见问题
文档即代码是不是一定比 Wiki 更适合企业产品手册？
不一定，要看手册里哪些部分必须和代码一起审查、一起发布。Mintlify 把文档即代码定义为：用 Markdown 或 MDX 写作、存放在 Git、经拉取请求审查，并通过自动化检查后发布；它同时写明，这一工作流更适合随产品变化的文档，人事政策和销售材料通常仍应留在这些团队已经在用的工具里。需要对不同读者按站点交付、且贡献者不以 Git 为日常工具时，可发布企业 Wiki 往往更合适。两类内容可以并存，但不应共用一份会分叉的「正式稿」。
接上浏览器编辑器和双向 Git 同步，还需要可发布知识库吗？
不一定互斥，但同步本身不等于按站点发布。GitBook 的 Git Sync 是仓库与文档站点之间的双向集成，官方提醒初始方向若选择 GitHub → GitBook，选定分支会替换对应分区，仓库为空或落后时，未导出的内容可能从已发布站点中丢失。浏览器编辑器降低的是写作门槛；阅读权限、内网预览与生产手册分别交付、草稿不进入公开站点，仍要单独验收。若这些能力已经在文档平台里按站点落实，可以不必再复制一套知识库；若还停在「仓库或编辑器里有最新稿」，就还缺少发布面。
产品手册能不能一部分放在 Git、一部分放在可发布 Wiki？
可以，而且常常更稳妥。随接口、SDK 和发行分支变化的参考文档，适合留在仓库里，走分支保护和持续集成；安装说明、故障排查、制度和要对客或按权限阅读的手册，适合进入可发布知识库，按应用同步到不同站点。两边只保留必要的交叉链接，不要各维护一份几乎相同、却都自称现行版本的正文。
把 Markdown 仓库同步进协作 Wiki，算不算已经做完文档治理？
不算。把仓库文件嵌入或发布到协作 Wiki，解决的是「工程师写在仓库里，其他人在 Wiki 里读得到」，并不自动等于生产手册只包含已审定版本，也不等于对外站点与内部门户使用不同权限。若目的地仍是「写完即可见」的协作空间，还要把协作 Wiki 和可发布 Wiki 的产品分界单独验收，见可发布企业 Wiki 的选型对照。
「保存」和「发布到站点」有什么区别？
在 Baklib 中，知识库编辑器里的「保存」只更新内容源，前台 Wiki 并不必然变化；必须在「应用发布」中对已绑定的 Wiki 应用执行「立即同步」，该站点的读者才会看到新版本。未同步的草稿不会进入公开 Wiki。文档即代码里也有类似分界：文件提交到功能分支，还不等于已合并进部署分支并完成生产构建。验收时应分别核对源文件是否更新、审定是否完成、目标发布面是否已刷新。
