Docs-as-Code

标签文章: Docs-as-Code

工具

如何选择文档生成器，而不是选择一种信仰

Sphinx、MkDocs、Astro 等工具针对不同内容模型和团队优化。应比较作者流程、扩展能力、本地化和维护成本，而不是只看演示页面和功能清单。

2 分钟阅读

工具

围绕“图表即代码：什么时候有用，什么时候没有”给出可执行、可验证并且便于长期维护的技术写作方法。从技术写作角度解释“图表即代码：什么时候有用，什么时候没有”，重点是可执行、可验证和可维护的做法。

3 分钟阅读

实践

Docs-as-Code 并不意味着把所有技术写作者都塞进 IDE。更合理的做法是把版本化文本、浏览器编辑、预览、有效的自动检查、人工评审和可预测发布组合起来。

3 分钟阅读

档案

格式和发布流水线变化巨大，但长期问题依旧熟悉：源文件控制、复用、导航、review，以及让已发布信息与产品保持同步。在“Docs-as-Code”这个名字出现之前，文档团队已经在处理多个源文件、共享片段、版本手册，以及“哪一份才是最新”的问题。

2 分钟阅读

工具

把文档当作构建产物：在读者看到改动之前验证结构、链接、示例和发布规则。 CI 不能判断解释是否真正有用，但可以在人工投入之前拦截大量可预测问题。

2 分钟阅读

工具

围绕“大规模 Markdown：避免仓库失控的约定”给出可执行、可验证并且便于长期维护的技术写作方法。从技术写作角度解释“大规模 Markdown：避免仓库失控的约定”，重点是可执行、可验证和可维护的做法。

3 分钟阅读