跳至主要内容
版本：最新版本 (v5.0.x)

Fastify 样式指南

欢迎​

欢迎来到 Fastify 样式指南。本指南旨在为编写我们开源框架开发者文档的用户提供一套规范的写作风格。每个主题都经过精确描述和详细解释，以帮助您编写用户易于理解和实施的文档。

本指南面向谁？​

本指南适用于任何热爱使用 Fastify 构建应用或希望为我们的文档做出贡献的人。您无需成为技术文档写作专家。本指南旨在为您提供帮助。

访问我们网站上的 贡献 页面或阅读 GitHub 上的 CONTRIBUTING.md 文件，加入我们的开源团队。

在您开始编写之前​

您需要了解以下内容

  • JavaScript
  • Node.js
  • Git
  • GitHub
  • Markdown
  • HTTP
  • NPM

考虑您的受众​

在开始写作之前，请思考您的目标读者。在本例中，您的受众应该已经了解 HTTP、JavaScript、NPM 和 Node.js。牢记您的读者至关重要，因为他们是您内容的消费者。您希望提供尽可能多的有用信息。考虑他们需要了解的关键事项以及他们如何理解这些事项。使用读者可以轻松理解的词汇和参考。征求社区的反馈，这可以帮助您编写更出色的文档，使其更关注用户和您想要实现的目标。

直奔主题​

为读者提供清晰而精确的操作步骤。从最重要的内容开始。这样，您可以帮助他们更快地找到所需内容。通常，读者倾向于阅读页面上的第一部分内容，许多人不会向下滚动。

示例

以下写法不够理想：冒号对于注册参数化路径非常重要。它让框架知道创建了一个新的参数。您可以在参数名称前放置冒号，以便创建参数化路径。

以下写法更佳：要注册参数化路径，请在参数名称前放置一个冒号。使用冒号可以让框架知道这是一个参数化路径而不是静态路径。

避免添加视频或图像内容​

不要在文档中添加视频或屏幕截图。这样更容易进行版本控制。随着新更新的不断开发，视频和图像最终会过时。相反，请提供一个参考链接或 YouTube 视频。您可以在 Markdown 中使用 [标题](www.websitename.com) 添加链接。

示例

To learn more about hooks, see [Fastify hooks](https://fastify.com.cn/docs/latest/Reference/Hooks/).

结果

要了解有关钩子的更多信息，请参阅 Fastify 钩子。

避免剽窃​

确保避免复制他人的作品。尽可能保持原创。您可以学习他们所做的事情，并在使用其作品中的特定引用时注明出处。

词汇选择​

在编写文档时，您需要使用和避免一些内容，以提高读者的可读性，并使文档简洁、直接和清晰。

何时使用第二人称“您”作为代词​

在撰写文章或指南时，您的内容应以第二人称（“您”）的直接形式与读者沟通。这使得更容易向他们提供关于特定主题的操作说明。要查看示例，请访问 插件指南。

示例

以下写法不够理想：我们可以使用以下插件。

以下写法更佳：您可以使用以下插件。

根据 维基百科，您 通常是第二人称代词。此外，还用于指代不确定的人，作为非常正式的不定代词的更常见替代。

何时避免使用第二人称“您”作为代词​

正式写作（例如参考文档或 API 文档）的主要规则之一是避免使用第二人称（“您”）或直接称呼读者。

示例

以下写法不够理想：您可以使用以下建议作为示例。

以下写法更佳：例如，应参考以下建议。

要查看实时示例，请参考 装饰器 参考文档。

避免使用缩写​

缩写是单词的书面和口语形式的简写形式，例如使用“don't”代替“do not”。避免使用缩写，以提供更正式的语气。

避免使用带有轻蔑意味的词语​

带有轻蔑意味的词语包括

  • 仅仅
  • 简单
  • 仅仅
  • 基本上
  • 显然

读者可能不会觉得使用 Fastify 的框架和插件很容易；避免使用使它听起来简单、容易、冒犯性或不敏感的词语。并非所有阅读文档的人的理解水平都相同。

以动词开头​

通常以动词开头您的描述，这使得读者更容易理解和遵循。更倾向于使用现在时，因为它比过去时或将来时更容易阅读和理解。

示例

以下写法不够理想：在能够使用 Fastify 之前，需要安装 Node.js。

以下写法更佳：安装 Node.js 以使用 Fastify。

语法语气​

语法语气是表达写作风格的一种好方法。避免在进行直接陈述时听起来过于强势。了解何时在陈述式、祈使式和虚拟式之间切换。

陈述式 - 用于进行事实陈述或提问。

示例：由于没有可用的测试框架，“Fastify 建议编写测试的方法”。

祈使式 - 用于提供说明、操作、命令或编写标题时。

示例：在开始开发之前安装依赖项。

虚拟式 - 用于提出建议、假设或非事实陈述。

示例：建议阅读我们网站上的文档，以全面了解该框架。

使用主动语态代替被动语态​

使用主动语态是传达文档内容的一种更简洁直接的方式。

示例

被动语态：节点依赖项和包由 npm 安装。

主动语态：npm 安装包和节点依赖项。

写作风格​

文档标题​

在 /docs/ 目录中创建新的指南、API 或参考时，请使用简短的标题来最佳地描述文档的主题。使用 kebab-case 命名您的文件，并避免使用 Raw 或 camelCase。要了解有关 kebab-case 的更多信息，您可以访问这篇关于 大小写样式 的 Medium 文章。

示例:

hook-and-plugins.md,

adding-test-plugins.md,

removing-requests.md.

超链接应具有清晰的参考目标标题。以下是您的超链接应有的格式

<!-- More like this -->

// Add clear & brief description
[Fastify Plugins] (https://fastify.com.cn/docs/latest/Plugins/)

<!--Less like this -->

// incomplete description
[Fastify] (https://fastify.com.cn/docs/latest/Plugins/)

// Adding title in link brackets
[](https://fastify.com.cn/docs/latest/Plugins/ "fastify plugin")

// Empty title
[](https://fastify.com.cn/docs/latest/Plugins/)

// Adding links localhost URLs instead of using code strings (``)
[http://localhost:3000/](http://localhost:3000/)

在您的文档中包含尽可能多的基本参考，但在为初学者编写内容时，避免使用过多的链接，以免分散注意力。