Plumego Docs 信息架构（IA）总览

定位：工程级框架文档，而不是教程集合

docs/
├── _index.md
├── intro/
├── getting-started/
├── concepts/
├── architecture/
├── core/
├── guides/
├── patterns/
├── advanced/
├── reference/
├── faq/
├── roadmap/
└── contributing/

下面逐层解释每一部分为什么存在、解决什么问题。

0. Docs Root

docs/_index.md

目的：
不是介绍 API，而是回答一个问题：

我该不该继续读这套文档？

内容建议：

• Plumego 是什么 / 不是什么
• 适合谁 / 不适合谁（链接到专题）
• 文档阅读路径推荐（不同角色）

1. Intro（价值与边界）

docs/intro/
├── _index.md
├── what-is-plumego.md
├── design-philosophy.md
├── tradeoffs.md
├── when-not-to-use.md
└── plumego-and-birdor.md

目标读者：正在做技术选型的人

设计原则：

• 不教代码
• 不讲 API
• 只讲判断

这是 Plumego 最重要的一层文档。

2. Getting Started（最低可运行路径）

docs/getting-started/
├── _index.md
├── installation.md
├── minimal-server.md
├── project-layout.md
└── first-request.md

目标读者：已决定“试用 Plumego”的工程师

关键原则：

• 只解决“跑起来”
• 不引入复杂概念
• 不提前谈最佳实践

3. Concepts（核心抽象说明）

docs/concepts/
├── _index.md
├── request-lifecycle.md
├── context.md
├── handler.md
├── middleware.md
├── router.md
└── error-model.md

这是 Plumego 的“理论核心”。

目标：

• 解释 Plumego 为什么这样设计
• 让读者形成稳定心智模型

重要原则：

• Concepts 文档 ≠ API 文档
• Concepts 文档 ≠ 教程

4. Architecture（工程结构与边界）

docs/architecture/
├── _index.md
├── layering.md
├── boundary-definition.md
├── domain-and-usecase.md
├── dependency-direction.md
└── monolith-to-services.md

目标读者：正在做架构设计的工程师

重点回答：

• Handler 到 Domain 的边界
• 哪些代码“永远不该依赖 Plumego”
• 如何避免框架侵入业务

5. Core（核心模块说明）

docs/core/
├── _index.md
├── http-server.md
├── router.md
├── middleware.md
├── context.md
├── response.md
└── lifecycle.md

这是“工程说明书”，不是教程。

原则：

• 精确
• 不夸张
• 不隐藏限制

每一章都应回答：

• 做了什么
• 没做什么
• 为什么不做

6. Guides（实战指导）

docs/guides/
├── _index.md
├── logging-and-traceid.md
├── panic-recovery.md
├── auth-and-jwt.md
├── request-validation.md
├── webhook-server.md
├── websocket.md
└── graceful-shutdown.md

目标：

• 把 Plumego 用在真实系统里
• 不引入“框架魔法”

风格：

• 示例驱动
• 不追求“最优解”
• 明确说明 tradeoff

7. Patterns（推荐模式）

docs/patterns/
├── _index.md
├── handler-thin.md
├── usecase-centric.md
├── middleware-composition.md
├── error-propagation.md
├── config-management.md
└── testing-strategy.md

这是 Plumego 的“经验层”。

回答的问题是：

在 Plumego 里，什么写法更安全？

⚠️ 明确说明：

• 这是 推荐
• 不是强制
• 不是规范

8. Advanced（高级与扩展）

docs/advanced/
├── _index.md
├── performance.md
├── custom-router.md
├── replacing-components.md
├── embedding-plumego.md
└── multi-service-setup.md

目标读者：已深度使用 Plumego 的团队

原则：

• 不提前暴露
• 不制造复杂度焦虑
• 明确风险点

9. Reference（参考手册）

docs/reference/
├── _index.md
├── public-apis.md
├── config-options.md
├── middleware-signatures.md
└── error-codes.md

这是唯一“偏手册”的区域。

特点：

• 无叙事
• 可查阅
• 不讲故事

10. FAQ（决策辅助）

docs/faq/
├── _index.md
├── plumego-vs-gin.md
├── plumego-vs-echo.md
├── why-not-framework-x.md
├── can-i-use-with-xxx.md
└── common-mistakes.md

目标：

• 减少重复问题
• 防止错误使用方式扩散

11. Roadmap（演进说明）

docs/roadmap/
├── _index.md
├── design-principles.md
├── planned-features.md
├── non-goals.md
└── versioning.md

非常重要的一点：明确 Non-goals，防止社区期待失控。

12. Contributing（贡献与治理）

docs/contributing/
├── _index.md
├── philosophy.md
├── code-structure.md
├── decision-process.md
├── pull-request-guide.md
└── documentation-guide.md

Plumego 的贡献文档，必须是“工程治理文档”，而不是“如何提 PR”。

技术文档写作规范

优秀的框架文档不仅是信息的堆砌，更需要精心设计的阅读体验。

命名规范

反模式清单

• 避免：开头写"本文将介绍…"——直接说是什么

• 避免：堆砌 API 参数列表——用场景说明

• 避免：只说"怎么做"不说"为什么"——概念层解释动机

• 避免：每个页面都推荐最佳实践——区分"推荐"和"可选"

• 推荐：每章开头回答——谁该读、读完能做什么

• 推荐：示例代码包含错误处理（不是理想情况）

• 推荐：明确标出局限性和不支持的特性

• 推荐：保持术语一致性（建立术语表）

维护策略

文档变更遵循与代码同等的审查标准：PR 中必须包含文档更新，重大特性缺失文档不得合并。建议维护术语表以保证全文一致性。

推荐阅读路径（Docs 内置）

在 docs/_index.md 中建议明确三条路径：

文档体系的价值

一套结构良好的技术文档不仅是产品的说明书，更是团队知识沉淀的核心载体。Plumego 采用的分层文档架构（从价值说明到实现参考）确保了不同角色的开发者都能快速找到所需信息，而不被无关内容干扰。最重要的设计决策是将"为什么"放在"怎么做"之前——选型文档比 API 文档更重要，概念说明比代码示例更优先。这种文档优先的工程文化，是从个人项目走向团队协作的必经之态。