documentation 是按读者需求组织技术文档的 Skill。本文介绍 mcollina/skills 的版本,它用 Diátaxis 把学习教程、操作指南、事实参考和原理解释分开。
第一次做项目的人需要能跟着完成的步骤;有经验的人通常只想解决眼前问题。查参数则要迅速找到类型、默认值与限制,不必先读一段故事。
不同内容可相互链接,避免教程反复被背景解释打断。但分类不是禁用表格或示例的规定,关键是让每页服务一个主要任务,术语与版本保持一致。
适合整理难找、难跟的文档。验收应按读者任务安排:能否做完、查到事实或理解原因。本文未测试真实读者;原文“30秒查到事实”是检验目标,不是成稿后自动获得的效果。