本文档概述了 Fuchsia 文档的标准、结构、基调和最佳做法。
文档位置
- 专门用于开发特定 Fuchsia 功能的文档：针对创建或维护 Fuchsia 代码库特定部分的开发者文档，应与源代码存放在同一目录中。这些文档通常采用嵌入到整个 Fuchsia 代码库中的
README.md文件的形式。 面向 Fuchsia 开发者的通用文档：应在
/HEAD/docs/中创建 Fuchsia 文档。在/docs/目录中，您应在以下某个子目录中创建文档：get-started：有关下载、设置和开始在 Fuchsia 上进行开发的具体指南，请参阅/docs/get-started。这些内容应包含有助于新用户开始使用 Fuchsia 的专业简短教程，并提供指向 Fuchsia.dev 中其他文档的链接。development：/docs/development/目录（在网站上显示为“指南”）包含面向使用 Fuchsia 的开发者的说明和教程。此目录包含有关如何构建、运行和测试 Fuchsia 的文档。concepts：/docs/concepts目录包含有关 Fuchsia 特定功能及其工作原理的深入说明，包括操作系统概览、框架、架构和软件包。reference：/docs/reference/目录包含生成的有关 Fuchsia 工具和 API 的参考文档，其中包括 FIDL 和内核参考文档。contribute：/docs/contribute/目录包含代码和文档贡献流程及最佳实践，包括文档代码和样式指南、代码政策以及治理。images/docs/images/目录包含文档中使用的图片。您应将图片放在此公共目录中。
文档类型
大多数文档可以分为以下几类：
- 程序化
- 使用入门 - 初始设置文档
- 指南 - 任务导向型文档
- 概念性 - 侧重于教授更多有关 Fuchsia、Fuchsia 架构和 Fuchsia 组件的基础文档
- 参考文档 - 详细说明 Fuchsia API 和工具的语法和参数的文档。这些文档通常是自动生成的。
如需了解详情，请参阅文档类型。
文档和代码样式指南
请务必遵循文档样式准则，以确保由大量贡献者创建的文档保持一致。如需获取具体文档指导，请参阅文档样式指南；如需获取代码示例指南，请参阅代码示例样式指南。
搜索网络最佳做法
文档只有在用户可以找到时才有用。一些可查找性和搜索方面的最佳实践包括：
- 将您的文档添加到目录中：在 fuchsia.dev 的左侧导航栏中添加指向文档的链接。如需了解详情，请参阅网站导航和 TOC 文件。
- 交叉链接文档：添加指向主题相关文档的链接，帮助读者更好地了解文档内容。例如，Fuchsia 模拟器的概念性文档链接到了有关 Fuchsia 模拟器的相关指南和入门文档。
- 使用一致的术语：如果您要撰写 Fuchsia 中的特定概念，请验证并确保使用的术语一致。使用术语库验证术语。
文档文件格式和文件名
Fuchsia 的所有文档均使用 Markdown (.md) 编写，Fuchsia.dev 使用 Hoedown Markdown 解析器。
网站导航由 _toc.yaml 文件配置，这些文件包含在每个文档目录中。请按照网站导航和 TOC 文件中的指南更新这些文件。
文件和目录名称应使用小写字母，并使用连字符而不是下划线分隔字词。在文件和目录名称中只能使用标准的 ASCII 字母数字字符。如果文件名包含带下划线的命令，那么您可以将下划线包含在内。
关于风格和语气的一般指南
使用简明的美国英语书写。用清晰、直白的美式英语撰写内容，确保内容简单易懂。使用简单字词、简明扼要，并使用 it's 或 don't 等缩写词。
相互尊重。遵循尊重规范中列出的准则。
以第二人称（“你”）撰写。Fuchsia 文档会写入用户（“您”）。例如，“您可以通过执行以下操作来安装 Fuchsia...”。请勿用第三人称的读卡器（“Fuchsia users can install Fuchsia by...”）或使用“We can install Fuchsia by...”。
书写时态。始终按原样记录系统，而不是现状。诸如“将会”之类的字词非常含糊。例如，“您将看到”会带来“什么时候会看到？”这样的问题。在 1 分钟还是 20 分钟后？此外，除非必要，否则不要提及未来的产品功能。提及未来可能不会发生的计划会成为维护负担。
确保句子简短具体。使用标点符号可让读者按照说明操作并理解概念。此外，短句更容易翻译。
了解您的受众群体。在撰写文档之前，请先定义您的受众群体。了解了观众之后，您就可以理解观众应该熟悉哪些信息。如果文档是面向更高级的受众群体，请在阅读文档之前预先说明，并让用户知道。
使用主动语态。尽量使用主动语态写作，因为被动语态会使句子含糊不清且难以理解。示例如下：
- 主动语态：“操作系统运行进程。”在这种情况下，主语会执行动词指示的操作。
- 被动语音：“进程正在运行。”主语不再主动，而是受动词操作 - 被动。在大多数情况下，如果您使用“by”，这表示您的句子可能仍采用被动语态。
如果您使用首字母缩写词，请在首次撰写相关邮件时定义词汇。例如，我觉得不错 (LGTM)。不要假设每个人都能理解所有首字母缩略词。您无需定义 TCP/IP 等业界标准的首字母缩略词。
定义技术术语并避免使用术语。所有级别的开发者都应访问 Fuchsia 文档。避免使用不常见或技术性很强的字词，避免造成文档过于复杂。如果您使用的是 Fuchsia 专用术语，请在术语表中进行定义。避免使用人造词汇。
避免使用口语化短语或地区习语。请注意，许多 Fuchsia 用户可能不是以英语为母语的用户。避免使用难以翻译的习语，例如“饼干就是这样”。虽然这对您来说可能意义明确，但并不能很好地翻译成其他语言。
避免引用专有信息。这可包括任何可能已注册为商标的术语或产品名称，或贵公司内部的任何内部信息（API 密钥、机器名称等）。
使用中性人称代词。请勿使用“he/she”中，也不要使用“he/she”或“其他”等标点符号。请改用 they.
使用一致的术语。确保代码、界面和文档中的术语一致。 尽可能使用常用术语，并使用术语库来验证术语。