/tags/docusaurus/ Recent content in docusaurus on Hugo -- gohugo.io en Fri, 10 Apr 2026 10:00:00 +0800 /posts/microservice-documentation-strategy-2026/ Fri, 10 Apr 2026 10:00:00 +0800 /posts/microservice-documentation-strategy-2026/ 在大规模微服务平台中，文档治理往往比架构设计本身更容易失控。Confluence、Notion 等中心化 wiki 工具在团队规模扩大后，很容易出现"文档漂移"（documentation drift）——文档与实际代码脱节，没人确定哪个版本更接近现状。 最近给自己的微服务项目搭文档站，选了 Docs-as-Code 这条路——文档和代码放同一个仓库，每个服务维护自己的 /docs/，最后用 Docusaurus 聚合成一个统一的门户。 这种模式和 Domain-aligned multi-repo 架构（每个 domain 有独立的 MS/BFF/consumer）比较契合：service owner 维护自己的 ADR 和设计文档，文档也更贴近代码；同时再通过 Docusaurus 提供统一入口。它和 Team Topologies 里 Stream-Aligned Team 的自治原则也比较一致。 这篇文章整理的是一套目前可落地的方案：组织结构、各服务 /docs/ 内容规范、Docusaurus 聚合机制、ADR 落地，以及我调研时看到的几种开源方案。 整体架构：三种仓库角色 在多仓库微服务平台中，文档体系涉及三种仓库角色： graph TD A["platform-architecture中央架构仓库"] -->|聚合| B["platform-docsDocusaurus 统一文档站"] C["MS repo"] -->|/docs/| B D["BFF repo"] -->|/docs/| B E["Consumer repo"] -->|/docs/| B 三种仓库的职责分工： 仓库类型 示例 文档职责 中央架构仓库 platform-architecture 全局架构概览、跨域决策、平台级 ADR、共享关注点（Kafka/Redis/Observability） 服务仓库 order-ms、user-bff 服务内部设计、服务级 ADR、API contract、Kafka 事件 schema、数据库 schema Docusaurus 文档站仓库 platform-docs 聚合所有来源的 Markdown，构建统一文档站（部署到 Vercel/Netlify） 这种分工的关键好处是：service owner 只需要维护自己 repo 的 /docs/，平台团队负责聚合和样式一致性。文档不一定会自动变好，但至少更不容易和代码长期脱节。