documentation-standards.md

文档标准概述

本文档概述了 Fuchsia 文档的标准、结构、语言风格和最佳做法。

文档定位

• 为开发 Fuchsia 具体特性的专门文档： 针对开发者创建或维护 Fuchsia 代码库特定部分的文档，应当和源代码保存在同一目录下。这类文档通常以 README.md 文件的形式嵌入在 Fuchsia 代码库中。

• 面向 Fuchsia 开发者的总体文档： Fuchsia 文档应当创建在 /HEAD/docs/ 中. 在 /docs/ 目录下，您应当在以下子目录之一内创建文档：

  • get-started: 有关下载、设置、开始 Fuchsia 开发的具体指南应当放进 /get-started。这类内容应当包含观点明确的、简短的教程，以帮助新用户入门 Fuchsia，并在 Fuchsia.dev 中链接至附加文档。
  • development: /development/ 目录（在网站上显示为“指南”（Guides））中包含了针对Fuchsia开发者的说明和教程。该目录包含关于如何构建、运行和测试 Fuchsia 的文档。
  • concepts: /concepts 目录包含针对 Fuchsia 具体特性及其工作原理的深入解释，包括操作系统概述、框架、架构和软件包（package）。
  • reference: /reference/ 目录包含自动生成的关于 Fuchsia 工具和 API 的参考文档，包括 FIDL 和内核的参考文档。
  • contribute: /contribute/ 目录包含代码和文档的贡献进度以及最佳做法，包含文档准则和风格指南、代码策略以及管理体系。
  • images /images/ 目录包含在文档中使用的图像。您应当将图像放在这一公共目录中。

文档类型

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

• 程序性的
  • 入门 - 初始设置的文档
  • 指南 - 任务导向的文档

• 概念性的 - 多侧重于教授 Fuchsia、Fuchsia 架构和 Fuchsia 组件的基础性文档

• 参考文档 - 侧重于详细说明 Fuchsia API 和 工具的语法和参数的文档。这类文档通常自动生成。

要获取更多信息，请参阅文档类型。

文档和代码风格指南

为确保由大量贡献者创建的文档都保持一致性，遵循文档风格指南很重要。要获取具体文档指导，请参阅文档风格指南；要获取代码样例指导，请参阅代码样例风格指南。

搜索的最佳做法

文档只有在用户能查到的时候才算有用。下面是一些关于可查性和搜索的最佳做法：

• 将您的文档添加至目录：在 fuchsia.dev 的左侧导航中添加文档链接。要获取更多信息，请参阅网站导航和目录文件

• 交叉链接文档：添加指向文档主题的链接，以帮助读者更好地理解文档的内容。 例如，[Fuchsia 模拟器] (/development/build/emulator.md) 的概念文档链接到有关 Fuchsia 模拟器的相关指南和入门文档。

• 使用一致的术语：如果您在撰写有关 Fuchsia 中特定概念的文章，请确认您使用的是一致的术语。 使用术语表来验证用语。

文档的文件格式和文件名

Fuchsia 的所有文档均使用 Markdown（.md）撰写，Fuchsia.dev 使用 Hoedown Markdown Parser 作为 Markdown 文档语法分析器。

该网站的导航是由 _toc.yaml 文件配置的，该文件包含在每个文档目录中。请使用网站导航和目录文件中的指导来更新这些文件。

文件和目录名应当为小写，并使用短横线（hyphen）而非下划线（underscore）来分隔单词。在文件或目录名中请仅使用标准 ASCII 字母数字字符。如果文件名包含带有下划线的命令，那么您可以包含下划线。

语言风格总体指导

• 使用通俗易懂的美国英语撰写。 使用清晰、直白的美国英语撰写，以使内容易于理解。请使用简单的词汇，保持简洁，并使用（常见）缩写，如 it's 或 don't。

• 心怀敬意。 请遵循尊重性规范中规定的方针。

• 使用第二人称（“you”）撰写。 Fuchsia文档是写给用户（“you”）的。例如，“您（you）可以通过以下步骤安装 Fuchsia……”。不要使用第三人称称呼读者（“Fuchsia 用户可以通过……安装 Fuchsia”）或使用“we”（“我们（we）可以通过……安装 Fuchsia”）。

• 使用现在时态撰写。 请在记录系统时始终立足眼下（it is），而非未来（it will be）。类似“will”之类的词语非常含糊。例如“您将看到”这种说法将引起如“我何时将会看到？”之类的问题。1分钟，还是20分钟呢？另外，若非必要，请不要提及未来的产品特性。提及可能取消的未来计划将导致维护上的困难。

• 保持语句简短具体。 使用标点符号可以便于您的读者跟进说明、理解概念。而且，短句更易于翻译。

• 了解您的受众群体。 在撰写文档之前，请确定好您的受众群体。了解受众群体使您能够明确他们应当熟悉的概念。当撰写面向更高级受众群体的文档时，请在文档前声明，让用户了解这一前提后，再进行阅读。

• 使用主动语态。 请尽量使用主动语态写作，因为被动语态会使句子模棱两可且难以理解。 下面是一个例子：
  • 主动语态：“操作系统运行一个进程。”（The operating system runs a process.）在这种情况下，主语执行动词表示的动作。
  • 被动语态：“一个进程正在被运行。”（A process is being run.）主语不再是“主动的”（active），而是被动词作用——它是“被动的”（passive）。 大多数情况下，如果您使用了“by”，那么您的句子可能仍然是被动语态。

• 若使用首字母缩写词，请您在第一次书写时进行定义。 例如，looks good to me（LGTM，我觉得看起来很好）。不要认为每个人都理解所有的首字母缩写词。您不需要定义工业标准首字母缩写词，如 TCP/IP。

• 定义技术术语，回避行话。 Fuchsia 文档应当易于各个层次的开发者理解。请避免使用不常用或高度技术性词语而使得文章过于复杂。如果您使用了 Fuchsia 特定的术语，请在术语表中对其进行定义。请回避自造词。

• 回避口头表达或地区习语。 请记住，许多 Fuchsia 用户并非英语母语者。请避免使用难于翻译的习语，例如“that's the way the cookie crumbles.”（生米已成熟饭/覆水难收）虽然对您而言能够理解，但是很难准确地翻译到其他语言中。

• 避免引用专有信息。 这里指的是任何可能是已注册商标的任何潜在词语或您公司的任何内部信息（API 密钥、机器名等）。

• 使用性别中立代词。 请不要使用 he，him，his，she 或 her，也不要使用 he/she 或 (s)he 等其他类似的符号表达方式。取而代之，请使用单数的 they。

• 使用一致的术语。 确保术语在代码、用户界面和文档中是一致的。尽可能使用常见术语，并使用术语表来验证用语。