Fastify 编程规范

欢迎

欢迎来到 Fastify 编程规范。本指南旨在为在我们的开源框架上编写开发者文档的用户提供一种约定俗成的写作风格。每个主题都经过精确且详细的解释，以帮助您撰写用户可以轻松理解和实现的文档。

该指南适用于谁？

本指南适用于任何喜欢使用 Fastify 构建应用或希望贡献于我们文档的人。您不需要是编写技术文档的专家。本指南旨在为您提供帮助。

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

在开始之前

你需要了解以下内容：

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

考虑你的读者

在开始写作前，请考虑你的读者。在这种情况下，你的读者应该已经熟悉HTTP、JavaScript、NPM和Node.js。始终要记住你的读者，因为他们是内容的消费者。你应该尽可能多地提供有用的信息。思考他们需要了解的重要事项以及如何理解这些信息。使用读者可以轻松关联的语言和参考文献。向社区寻求反馈可以帮助你编写更注重用户需求和技术目标的文档。

直入主题

给读者一个清晰明确的操作指南。从最重要的内容开始，这样可以帮助他们更快地找到所需的信息。通常情况下，读者倾向于阅读页面上的第一部分内容，并且很多人不会继续滚动浏览其他部分的内容。

示例

不要像这样写：冒号对于注册参数路径非常重要。它让框架知道有一个新的参数被创建了。你可以在参数名之前放置冒号以创建参数路径。

更应该像这样写：要注册一个参数路径，请在参数名称前加上冒号。使用冒号可以让框架知道这是一个参数路径而不是静态路径。

避免添加视频或图片内容

不要将视频或截图添加到文档中，因为这些内容更容易被版本控制系统管理。随着新更新的不断推出，视频和图像最终会变得过时。相反，请创建一个参考链接或YouTube视频。你可以通过使用 [Title](www.websitename.com) 在Markdown中添加链接。

示例

要了解有关钩子的更多信息，请参阅 [Fastify 钩子](https://fastify.dev/docs/latest/Reference/Hooks/)。

结果：

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

避免抄袭

确保不要复制他人的作品。保持原创性。您可以从他们的工作中学到东西，并在使用他们工作的特定引用时注明出处。

用词选择

在编写文档时，有一些词语和表达方式需要使用或避免，以提高可读性，并使文档整洁、直接且清晰。

在何时使用第二人称“你”作为代词

当你撰写文章或指南时，内容应该直接面向读者（使用第二人称“你”的形式）。这样更容易给读者提供具体的指示和建议。例如，请参阅插件指南。

示例

不要像这样写：我们可以使用以下插件。

而是这样写：你可以使用以下插件。

根据Wikipedia，你 通常是第二人称代词。 同时，也可以用来指代不确定的某个人，作为非常正式的不定代词的一种更常见的替代形式。

避免使用第二人称“你”作为代词

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

示例

不要这样写：你可以将以下建议用作示例。

改为这样写：以下推荐应作为一个例子进行引用。

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

避免使用缩略语

缩略语是单词的简化形式，例如使用“don’t”代替“do not”。避免使用缩略语以提供更正式的语气。

避免使用贬低性词语

贬低性词语包括：

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

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

使用动词开头

尽量用动词开始你的描述，这使得读者更容易理解和跟随。优先使用现在时态，因为它比过去时态或将来时态更易于阅读和理解。

示例

不要这样写：在可以使用Fastify之前需要安装Node.js。

改为这样写：安装Node.js以使用Fastify。

语气

使用不同的语法语气可以更好地表达你的写作。避免在直接陈述时显得过于强硬，知道何时切换到直陈式、命令式和虚拟式。

直陈式 - 在陈述事实或提出问题时使用。

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

命令式 - 在给出指令、动作或写标题时使用。

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

虚拟式 - 在提供建议、假设或非事实陈述时使用。

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

使用 主动语态 而不是 被动语态

使用主动语态可以更简洁直接地传达你的文档内容。

示例

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

主动语态：npm 安装了 Node 依赖项和包。

写作风格

文档标题

在 /docs/ 目录中创建新的指南、API 或参考文档时，使用简洁且能最好地描述主题的短标题。将文件名用连字符分隔（kebab-case），避免使用 Raw 或 camelCase 格式。有关 kebab-case 的更多信息，请参阅 Case Styles  这篇文章。

示例:

hook-and-plugins.md,

adding-test-plugins.md,

removing-requests.md.

超链接

超链接应具有清晰的标题，说明其指向的内容。以下是超链接应该呈现的样子：

<!-- 更像这样 -->

// 添加简洁且明确的描述
[Fastify 插件](https://fastify.dev/docs/latest/Plugins/)

<!-- 不要像这样 -->

// 描述不完整
[Fastify] (https://fastify.dev/docs/latest/Plugins/)

// 在链接方括号中添加标题
[](https://fastify.dev/docs/latest/Plugins/ "fastify plugin")

// 空白标题
[](https://fastify.dev/docs/latest/Plugins/)

// 使用超链接而不是代码字符串（``）来添加本地主机 URL
[http://localhost:3000/](http://localhost:3000/)

在文档中尽可能多地包含必要的参考内容，但避免在为初学者编写时使用过多的链接以减少干扰。