云服务网站的技术内容组织方法

云服务产品的技术文档往往随着功能迭代不断膨胀，不同写作目的的内容混排在同一目录下，导致读者难以快速找到所需信息。本文以Diátaxis框架为基础，说明如何将云服务文档按教程、操作指南、技术参考和解释说明四种类型进行分类组织，并给出目录结构、导航写法和日常维护方面的具体建议。¹²

一个假设的对象存储文档目录

以下是一个假设的对象存储产品文档目录，用于说明常见的内容混排问题。假设某云服务提供商的对象存储文档目录如下：第一层为快速入门、控制台操作、API参考、最佳实践和常见问题五个入口。快速入门下包含创建存储桶、上传第一个文件、设置访问权限三篇文档；控制台操作下包含创建存储桶、上传文件、设置生命周期规则、配置跨区域复制、设置访问权限、查看监控指标六篇文档；API参考下包含PutObject、GetObject、DeleteObject等接口说明；最佳实践下包含存储桶命名规范、大文件上传策略、权限最小化原则三篇文档；常见问题下包含上传失败排查、权限报错处理等十余篇问答。

在这个假设目录中，创建存储桶同时出现在快速入门和控制台操作两个位置，设置访问权限也是如此。快速入门中的创建存储桶实际上是一篇引导新手完成首次操作的教程，而控制台操作中的同名文档则假定读者已有基础、直接给出配置步骤，属于操作指南。两篇文档的写作目的不同，但因为标题相同且分属不同目录，读者难以区分该看哪一篇。¹

最佳实践下的存储桶命名规范混合了命名规则的技术描述和选择建议的解释性讨论；大文件上传策略既包含分片上传的操作步骤，又包含何时该用分片的原理说明。这种混排使得读者在查阅精确信息时被迫阅读无关内容，在学习概念时被操作步骤打断。

这个假设示例反映的问题在云服务文档中很常见：随着产品功能增加，不同写作目的的内容被堆放在同一层级，读者无法根据自己的当前需求快速定位。Diátaxis将文档划分为四种类型：教程、操作指南、技术参考和解释说明，并认为文档应当围绕这些需求的结构来组织。¹

按四种类型分类现有文档的步骤

Diátaxis的实践指南指出，不需要完全理解其理论原则就可以开始应用，关键原则可以通过直觉把握。以下是本文建议的分类步骤，适用于已有一定文档积累但结构混乱的云服务产品。²

步骤 1

清点现有文档清单。将产品文档站中所有页面列出，记录每篇的标题和当前所在目录位置。不需要逐篇阅读内容，先建立全局视图。

步骤 2

逐篇判断当前内容主要服务于哪类需求：是帮助新手建立操作信心，还是指导有经验的用户完成特定目标，是提供精确的技术描述供查阅，还是解释概念和原理以增进理解。²³

步骤 3

标记混合内容。如果一篇文档中同时包含操作步骤和概念解释，或者既有API参数列表又有使用建议，将其标记为需要拆分的候选。本文建议以段落为最小单位进行判断，而非以整篇文档为单位。

步骤 4

为每篇文档标注目标类型。教程对应学习导向的体验，操作指南对应目标导向的方向指引，技术参考对应信息导向的技术描述，解释说明对应理解导向的讨论。标注时参考Diátaxis对四种类型的定义，而非凭个人感觉。²

步骤 5

执行拆分和归位。将标记为混合内容的文档拆分为独立页面，每篇只保留一种类型的内容。拆分后的页面按类型归入对应目录。对于无法明确归类的段落，本文建议暂时放入解释说明类，后续再根据读者反馈调整。

四种文档类型的定义与区分

Diátaxis基于两个维度构建其分类体系：行动与认知、获取与应用。行动指实践性知识，即知道怎么做；认知指理论性知识，即知道是什么。获取指处于学习阶段，应用指处于工作阶段。两个维度交叉形成四个象限，每个象限对应一种文档类型。³

教程服务于正在获取技能的用户，为其行动提供信息。在云服务场景中，一篇教程可能引导新手完成第一次创建存储桶并上传文件的全过程，重点在于让读者跟随步骤获得成功体验，而非覆盖所有配置选项。³

操作指南服务于正在应用技能的用户，为其行动提供信息。与教程不同，操作指南假定读者已经具备基础能力，直接针对特定目标给出步骤。例如，一篇关于配置跨区域复制规则的操作指南不需要解释什么是对象存储，而是直接进入配置流程。²³

技术参考服务于正在应用技能的用户，为其认知活动提供信息。它是信息导向的技术描述，在云服务中通常表现为API文档、参数表、错误码列表、配额说明等。参考文档的特点是结构严谨、内容精确，读者按需查阅而非顺序阅读。²³

解释说明服务于正在获取技能的用户，为其认知活动提供信息。它是理解导向的讨论，帮助读者建立对系统行为和设计理念的认识。例如，解释对象存储的一致性模型、生命周期策略的触发机制等，都属于这一类型。²³

目录结构与导航的本文建议

以下关于目录结构、入口设置和导航写法的方案均为本文建议，不代表任何厂商的实际做法，读者可根据自身产品文档的规模和团队情况调整。

本文建议的顶层目录按文档类型划分，设置四个一级入口：教程、操作指南、参考、解释说明。在每个类型内部，再按产品功能模块组织二级目录。以假设的对象存储产品为例，操作指南下可按存储桶管理、对象操作、访问控制、数据生命周期等模块组织；参考下可按API接口、错误码、配额限制等维度组织。¹

导航文案的写法也需要区分类型。本文建议教程标题使用动宾结构并体现学习成果，例如“创建你的第一个存储桶并上传文件”，让读者一眼看出完成后的收获。操作指南标题应直接指向任务目标，例如“配置跨区域复制规则”，省略不必要的修饰词。技术参考标题使用接口名或资源名等精确标识，例如“PutObject”“错误码列表”。解释说明标题则用概念性短语概括讨论主题，例如“对象存储的一致性模型如何工作”。四种标题风格的区别本身就构成导航线索，帮助读者在目录层级中快速判断哪篇文档匹配自己当前的需求状态。

本文还建议在每个一级入口的落地页放置简短的适用范围说明。例如教程入口页可以写一句话概括：“这里的文档面向首次接触本产品的用户，引导你完成基础操作并建立信心。”这类说明帮助读者在选错入口时快速自我纠正，减少无效浏览。

分类质量的检验方法

Diátaxis的理论基础指出，四种文档类型是对服务实践者需求的完整枚举，不存在第五种类型。这意味着任何一篇文档都应该能明确归入其中一类。如果在分类过程中发现某篇内容确实无法归类，本文建议首先检查是否属于混合内容需要拆分，其次检查是否对四种类型的定义理解有偏差。³

本文建议的检验方法有两个。第一，读者视角检验：想象一个具体读者在特定场景下打开这篇文档，他是在学习、在执行任务、在查信息还是在理解概念？如果答案不唯一，说明内容混合了多种类型。第二，删除检验：假设删去文档中的某一段，剩余内容是否仍然完整服务于同一类需求？如果是，说明被删去的段落属于另一种类型，应当拆出。

Diátaxis的实践指南强调，不需要等到完全理解框架才开始应用，而是在实践中迭代理解。本文建议文档团队在初次分类时不必追求完美，先按当前理解完成一轮分类，在实际使用中根据读者反馈持续调整。分类本身是一个渐进过程，而非一次性工程。²

常见问题

教程和操作指南的边界在哪里？

根据Diátaxis框架，教程是面向学习的体验，帮助新手在引导下完成一系列操作以建立信心；操作指南是面向目标的方向指引，假定读者已具备基础能力，直接指导完成特定任务。判断标准在于读者是否已经知道自己要做什么：如果读者还在学习阶段，内容属于教程；如果读者已有明确目标只需步骤，内容属于操作指南。²³

一篇文档同时包含步骤和概念解释时应该怎么处理？

本文建议将混合内容拆分为独立文档。操作步骤归入操作指南或教程，概念解释归入解释说明类文档，两者之间通过链接互相引用。这样每篇文档只服务一种需求，读者可以根据自己当前的状态直接找到对应内容，而不会被无关信息干扰。¹

技术参考文档应该包含哪些内容？

根据Diátaxis的定义，技术参考是面向信息的技术描述，服务于正在应用技能的用户，为其认知活动提供精确信息。在云服务场景中，这通常包括API端点列表、参数说明、返回值格式、错误码、配额限制等结构化信息。本文建议参考文档保持与产品实际行为严格一致，不加入使用建议或评价。¹

文档目录应该按产品功能模块划分还是按用户任务划分？

本文建议两者结合：顶层目录按文档类型（教程、操作指南、参考、解释）划分，使读者能快速定位所需内容形式；在每个类型内部，再按功能模块或任务场景组织。这样既保留了Diátaxis框架的分类优势，又不丢失按功能查找的便利性。具体层级深度需根据文档总量调整。¹

如何判断现有文档的分类是否正确？

本文建议用两个问题检验：第一，这篇文档的读者在使用它时处于什么状态——是在学习新技能、在执行已知任务、在查阅精确信息，还是在理解某个概念？第二，如果删去这篇文档中的某一段，剩余内容是否仍然完整服务于同一类需求？如果答案不一致，说明内容混合了不同类型，需要拆分。³