工具

标签文章: 工具

工具

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

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

2 分钟阅读

工具

围绕“选择文档搜索：从失败查询开始”给出可执行、可验证并且便于长期维护的技术写作方法。从技术写作角度解释“选择文档搜索：从失败查询开始”，重点是可执行、可验证和可维护的做法。

3 分钟阅读

工具

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

3 分钟阅读

档案

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

2 分钟阅读

工具

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

2 分钟阅读

工具

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

3 分钟阅读

工具

样式 linting 最有价值的地方，是发现术语漂移、风险措辞和可重复的编辑缺陷。规则应少而明确，并保持足够安静，让一次失败真正值得作者注意。样式 linter 可以在几秒内检查成千上万句子，因此很容易产生“把所有偏好都编码进去”的冲动。

2 分钟阅读

档案

围绕“当用户手册随 CD 一起交付”给出可执行、可验证并且便于长期维护的技术写作方法。从技术写作角度解释“当用户手册随 CD 一起交付”，重点是可执行、可验证和可维护的做法。

2 分钟阅读