文档类型

文档是任何产品或功能的重要组成部分，因为它可让用户了解如何使用已实现的功能。本文档是介绍文档类型的简单快捷参考。

如需了解常规文档标准（包括文件类型、位置和常规色调），请参阅 Fuchsia 文档标准。如需有关字词选择、样式和结构的具体指南，请参阅紫红色文档样式指南。

过程（指南）、概念或参考文档

大多数文档可以分为以下几类：

  • 流程（指南）
    • 使用入门 - 介绍如何设置 Fuchsia 开发环境的分步流程（例如下载和构建 Fuchsia）的文档。它们位于 /docs/get-started 下。
    • 开发，也称指南 - 用于分步执行与 Fuchsia 相关的任务的文档。它们都位于 /docs/development/ 下。
  • 概念 - 帮助您了解 Fuchsia 中的 mod 等概念的文档。此类文档位于 /docs/concepts 下。
  • 参考文档 - 提供系统各部分相关信息来源（例如 API 参数或 FIDL）的文档。它们位于 /docs/reference/ 下。许多参考文档是自动生成的。

如果您计划向用户说明如何使用特定功能，并能够指导用户完成简单的编号步骤，则应该编写一份程序文档。程序文档通过提供一个或多个可能对用户有用的示例来强调概念性文档中解释的概念。

如果您计划解释产品的概念，则应该撰写概念性文档。 概念性文档会解释一个具体概念，但在大多数情况下并不包含实际示例。它们提供基本事实、背景和图表，帮助读者对产品或主题建立基本了解。您不应解释受众群体应该熟悉的业界标准，例如 TCP/IP。您可以说明此概念与您的特征之间的关联，但不应该解释该行业标准概念背后的基础知识。

如果您需要提供有关系统各个部分（包括但不限于 API 和 CLI）的信息，请编写参考文档。参考文档应让用户能够快速轻松地了解如何使用特定功能。

程序文档

程序文档应尽量简短，文档中的每个任务都应尽量避免执行上述 10 个步骤。您应将较长的过程划分为多个子任务，以尽量确保任务便于用户管理。

例如，如果要编写一个照顾狗狗的流程文档，您可以创建一个如下所示的内容表：

如何照顾狗：

  • 喂狗
  • 洗狗
  • 修剪狗指甲
  • 为狗毛刷毛

一般程序文档准则

  • 每个任务或子任务都应该有一个段落，让用户了解任务的内容以及用户在执行该任务或子任务后应能够做什么。
  • 使用屏幕截图或图形来帮助用户在界面 (UI) 中导航。

  • 程序文档不应要求用户解释任何概念，但应引用概念性文档，以防用户不了解特定概念。例如，引用概念性文档的过程可能如下所示：

    为服务器配置适当的配置。如需详细了解服务器配置，请参阅“服务器配置”。

  • 在完成相关程序时，避免为用户提供多个路径选择。当您避免为用户提供选项时，您的文档应将所有用户引向相同的最终结果。

  • 如果程序文档适用于新手用户，请避免添加您认为更适合高级用户的程序。如果您的文档面向高级用户，请事先说明并向他们提供前提条件列表，然后再学习您的方法指南或 Codelab。

  • 如果您要在程序文档中加入代码示例，请参阅代码示例样式准则中详述的最佳实践。

概念文档

概念文档应尽量简短，大多不要超过一页。 如果您需要编写多个页面来描述某个概念，请考虑使用标题将该概念拆分为多个子概念。通过让文档保持简洁，您可以实现以下目标：

  • 不要写满一堆文字，让读者感到无所适从。
  • 避免读者在阅读您的文档时丢失。

第一段应尽量简短地对文档进行总结，以便用户快速通读文档、确定文档内容，以及这些内容与他们想要了解的内容是否相关。如果文档具有多个标题，则应在第一段后面添加一个项目符号列表，其中概括介绍标题。

您应使用图形、图像或图表来强化某些概念。图形前后的文字应解释图形显示的内容。图片应保存在功能专属的“images/”目录或通用的“images/”目录中。您还应将图片的源文件保存在“images/src/”目录中。

好的概念性文档通常包括：

  • 说明而非说明
  • 背景概念
  • 图表或其他视觉辅助工具（最好采用 .png 格式）
  • 指向过程文档和/或参考文档的链接

编写文档后，最好校对文档，设身处地为用户着想（不再是开发相应功能的专家），并尝试回答以下问题：

  • 文档中的信息是否完整解释了相关概念？
  • 有没有这个概念不需要的信息？如果是，请将其移除。
  • 是否有不必要的细节说明事情的后台运行方式？
  • 如果是用户，我还想了解其他事项吗？

然后，如果这些问题未得到完全解答，请重新修改您的文档。

参考文档

参考文档应提供有关系统各个部分（包括但不限于 API 和 CLI）的信息。相应类型的所有参考文档的样式都应相同。例如，API 文档应定义 API 的所有参数，指明参数是必需还是可选，并展示 API 的使用示例。这些示例应该非常宽泛和简单。如果您需要一个更详细的示例，请考虑创建一个程序性文档来强化您的参考文档。

如需查看 API 文档的样式指南，请参阅 API 样式指南。