文档与内容类型

同一产品需要 多种文档形态 服务不同意图。混淆类型会导致用户打开 Tutorial 却只想查参数表——浪费双方时间。

学习目标

• 区分 Tutorial、How-to、Reference、Explanation 四类文档
• 掌握 Troubleshooting 与 Release Notes 的写作要点
• 为 CodeRoadMap 类平台选择合适的文档组合

核心概念

Diátaxis 四象限

类型	用户意图	示例
Tutorial	跟着做，建立信心	「30 分钟创建第一个 track」
How-to	完成具体任务	「如何批量导入 lesson」
Reference	查字段、参数、错误码	POST /api/tracks 请求体
Explanation	理解设计与权衡	「为何 slug 全局唯一」

Tutorial 偏线性；How-to 可跳转；Reference 要完整；Explanation 讲 why 不讲步骤。

Troubleshooting 结构

症状 — 用户看到的错误（HTTP 409、日志片段）
原因 — 常见根因 ranked by 频率
解决 — 逐步操作，含验证命令
仍不行 — 收集信息模板 + Support 链接

好排错文档 可复制粘贴：命令、配置片段、期望输出一行对照。

Release Notes

• Audience：升级系统的运维与开发者
• Must have：Breaking changes、Migration 步骤、Deprecation 时间表
• Nice to have：性能改进、Bug fix 分类（Security 置顶）

避免复制 commit message 堆砌；按 用户影响 分组。

CodeRoadMap 文档组合建议

/docs/quickstart — Tutorial
/docs/guides/import-lessons — How-to
/docs/api/tracks — Reference
/docs/concepts/track-model — Explanation
/docs/releases — Release Notes

练习

• 将「用户不会调 tracks API」拆成 Tutorial vs How-to 各写 3 条大纲
• 为 HTTP 409 Conflict 写 Troubleshooting 骨架（症状 / 原因 / 解决）
• 草拟 v1.1 Release Notes：新增字段 estimated_weeks 的说明

小结

文档类型由用户任务决定；类型对了，篇幅与语气自然对齐。 下一课进入 SEO 与关键词策略。