从内容开始，而不是从主题截图开始
一个漂亮的 demo 完全可能不适合你的文档。先列出系统必须发布什么：长手册、API reference、教程、生成页面、多版本、多语言、数千篇文章，还是它们的组合。
再描述谁负责写作。每天在 Git 里编辑 Markdown 的工程师，与偶尔通过浏览器贡献内容的专家需求不同。
比较内容模型
Sphinx 在交叉引用、结构化 directive、长技术文档和扩展性方面很强。MkDocs 适合 Markdown-first 流程和相对直接的网站结构。Astro 是更通用的 content-focused web framework，提供 typed content collections、assets、routing 和 layout 的高度控制，但团队也需要承担更多发布产品本身的工作。
目标不是选出冠军，而是让抽象与工作匹配。
计算维护面
统计自定义插件、主题 override、build step 和内部约定。每项定制都会在未来升级时产生成本。不要只问“能不能改”，还要问“下一个维护者能不能理解为什么这样改”。
原型最困难的场景
用真实的难点做 spike：大表格、reuse、本地化、代码高亮、图片、redirect、搜索元数据和长文章。使用有代表性的页面数量测试 build。
不要只评估首页。
保留迁移能力
尽量把内容语义与特定主题标记分开。优先普通 Markdown 与明确定义的组件，而不是大量临时 HTML。把元数据放入有文档说明的 schema。
生成器是基础设施，不是身份。选择能让今天的发布可靠，并为明天留下合理退出路径的工具。
实践示例
把《如何选择文档生成器，而不是选择一种信仰》当作一次小型评估，而不是功能列表比较。选择三类真实内容：简单页面、包含代码或结构化数据的页面，以及带有导航、复用或本地化要求的复杂页面。用同一种工具或方法处理三者，并记录哪些工作变简单、哪些新的维护成本出现。
重点检查团队会重复进行的工作：
- 作者是否容易理解源文件；
- 审阅者是否能看出有意义的差异；
- 构建失败是否指出可以修复的问题；
- 内容能否在无需大量手工清理的情况下移动、翻译和复用。
好的工具会减少写作、审阅和发布中的不确定性。如果复杂性只是转移到脆弱配置、插件或某个专家的记忆中，也必须把它计入成本。
快速编辑检查
- 从内容开始，而不是从主题截图开始. 一个漂亮的 demo 完全可能不适合你的文档。
- 比较内容模型. Sphinx 在交叉引用、结构化 directive、长技术文档和扩展性方面很强。
- 计算维护面. 统计自定义插件、主题 override、build step 和内部约定。
- 原型最困难的场景. 用真实的难点做 spike：大表格、reuse、本地化、代码高亮、图片、redirect、搜索元数据和长文章。
