Fastify 风格指南

¥Fastify Style Guide

欢迎

¥Welcome

欢迎来到 Fastify 风格指南。本指南旨在为你在我们的开源框架上编写开发者文档的用户提供传统的写作风格。每个主题都精确且解释良好，可帮助你编写用户可以轻松理解和实现的文档。

¥Welcome to Fastify Style Guide. This guide is here to provide you with a conventional writing style for users writing developer documentation on our Open Source framework. Each topic is precise and well explained to help you write documentation users can easily understand and implement.

本指南适合谁？

¥Who is this guide for?

本指南适用于任何喜欢使用 Fastify 进行构建或想要为我们的文档做出贡献的人。你不需要成为编写技术文档的专家。本指南旨在为你提供帮助。

¥This guide is for anyone who loves to build with Fastify or wants to contribute to our documentation. You do not need to be an expert in writing technical documentation. This guide is here to help you.

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

¥Visit the contribute page on our website or read the CONTRIBUTING.md file on GitHub to join our Open Source folks.

在你写之前

¥Before you write

你需要了解以下信息：

¥You need to know the following:

• JavaScript

• Node.js

• git

• GitHub

• Markdown

• HTTP

• NPM

考虑你的受众

¥Consider your Audience

在开始写作之前，请考虑一下你的读者。在这种情况下，你的受众应该已经了解 HTTP、JavaScript、NPM 和 Node.js。有必要牢记你的读者，因为他们是消费你内容的人。你想提供尽可能多的有用信息。考虑他们需要知道的重要事情以及如何理解这些事情。使用读者可以轻松联想到的词语和参考文献。向社区寻求反馈，它可以帮助你编写更好的文档，重点关注用户和你想要实现的目标。

¥Before you start writing, think about your audience. In this case, your audience should already know HTTP, JavaScript, NPM, and Node.js. It is necessary to keep your readers in mind because they are the ones consuming your content. You want to give as much useful information as possible. Consider the vital things they need to know and how they can understand them. Use words and references that readers can relate to easily. Ask for feedback from the community, it can help you write better documentation that focuses on the user and what you want to achieve.

开门见山

¥Get straight to the point

为你的读者提供清晰、准确的行动建议。从最重要的事情开始。这样，你可以帮助他们更快地找到他们需要的东西。大多数情况下，读者倾向于阅读页面上的第一个内容，许多人不会继续滚动。

¥Give your readers a clear and precise action to take. Start with what is most important. This way, you can help them find what they need faster. Mostly, readers tend to read the first content on a page, and many will not scroll further.

示例

¥Example

少这样的：冒号对于注册参数路径非常重要。它让框架知道创建了一个新参数。你可以将冒号放在参数名称之前，以便可以创建参数路径。

¥Less like this: Colons are very important to register a parametric path. It lets the framework know there is a new parameter created. You can place the colon before the parameter name so the parametric path can be created.

更多类似这样的：要注册参数路径，请在参数名称前添加冒号。使用冒号让框架知道它是参数路径而不是静态路径。

¥More Like this: To register a parametric path, put a colon before the parameter name. Using a colon lets the framework know it is a parametric path and not a static path.

避免添加视频或图片内容

¥Avoid adding video or image content

请勿在文档中添加视频或屏幕截图。更容易保持版本控制。随着新更新的不断发展，视频和图片最终将变得过时。相反，制作推荐链接或 YouTube 视频。你可以在 markdown 中使用 [Title](www.websitename.com) 添加链接。

¥Do not add videos or screenshots to the documentation. It is easier to keep under version control. Videos and images will eventually end up becoming outdated as new updates keep developing. Instead, make a referral link or a YouTube video. You can add links by using [Title](www.websitename.com) in the markdown.

示例

¥Example

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

结果：

¥Result:

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

¥To learn more about hooks, see Fastify hooks.

避免抄袭

¥Avoid plagiarism

确保避免抄袭他人的作品。尽可能保持原创。如果你使用了他们作品中的特定引用，你可以从他们所做的事情中学习并参考其出处。

¥Make sure you avoid copying other people's work. Keep it as original as possible. You can learn from what they have done and reference where it is from if you used a particular quote from their work.

选词

¥Word Choice

在编写文档时，你需要使用和避免一些事情，以提高读者的可读性并使文档整洁、直接和干净。

¥There are a few things you need to use and avoid when writing your documentation to improve readability for readers and make documentation neat, direct, and clean.

何时使用第二人称 "你" 作为代词

¥When to use the second person "you" as the pronoun

撰写文章或指南时，你的内容应以第二人称（"你"）寻址形式直接与读者沟通。直接指导他们如何处理特定主题会更容易。要查看示例，请访问 插件指南。

¥When writing articles or guides, your content should communicate directly to readers in the second person ("you") addressed form. It is easier to give them direct instruction on what to do on a particular topic. To see an example, visit the Plugins Guide.

示例

¥Example

少这样的：我们可以使用以下插件。

¥Less like this: we can use the following plugins.

更多类似这样的：你可以使用以下插件。

¥More like this: You can use the following plugins.

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

¥According to Wikipedia, You is usually a second person pronoun. Also, used to refer to an indeterminate person, as a more common alternative to a very formal indefinite pronoun.

何时避免第二人称 "你" 作为代词

¥When to avoid the second person "you" as the pronoun

正式写作（例如参考文档或 API 文档）的主要规则之一是避免使用第二人称（"你"）或直接向读者致辞。

¥One of the main rules of formal writing such as reference documentation, or API documentation, is to avoid the second person ("you") or directly addressing the reader.

示例

¥Example

少这样的：你可以使用以下建议作为示例。

¥Less like this: You can use the following recommendation as an example.

更多类似这样的：例如，应参考以下建议。

¥More like this: As an example, the following recommendations should be referenced.

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

¥To view a live example, refer to the Decorators reference document.

避免使用缩写

¥Avoid using contractions

缩写是单词的书面和口头形式的缩写，即使用 "不要" 而不是 "不要"。避免收缩以提供更正式的语气。

¥Contractions are the shortened version of written and spoken forms of a word, i.e. using "don't" instead of "do not". Avoid contractions to provide a more formal tone.

避免使用居高临下的术语

¥Avoid using condescending terms

居高临下的术语包括：

¥Condescending terms are words that include:

• 只是

  ¥Just

• 简单的

  ¥Easy

• 简单地

  ¥Simply

• 基本上

  ¥Basically

• 明显地

  ¥Obviously

读者可能觉得 Fastify 的框架和插件使用起来并不容易；避免使用听起来简单、容易、令人反感或麻木不仁的词语。并非每个阅读文档的人都具有相同程度的理解。

¥The reader may not find it easy to use Fastify's framework and plugins; avoid words that make it sound simple, easy, offensive, or insensitive. Not everyone who reads the documentation has the same level of understanding.

以动词开头

¥Starting with a verb

大多数情况下以动词开始描述，这使得读者可以简单而准确地理解。更喜欢使用现在时，因为它比过去时或将来时更容易阅读和理解。

¥Mostly start your description with a verb, which makes it simple and precise for the reader to follow. Prefer using present tense because it is easier to read and understand than the past or future tense.

示例

¥Example

少这样的：在使用 Fastify 之前需要安装 Node.js。

¥Less like this: There is a need for Node.js to be installed before you can be able to use Fastify.

更多类似这样的：安装 Node.js 以使用 Fastify。

¥More like this: Install Node.js to make use of Fastify.

语法语气

¥Grammatical moods

语法情绪是表达写作的好方法。直接发表声明时，避免听起来过于专横。知道何时在指示语气、命令语气和虚拟语气之间切换。

¥Grammatical moods are a great way to express your writing. Avoid sounding too bossy while making a direct statement. Know when to switch between indicative, imperative, and subjunctive moods.

指示性 - 在做出事实陈述或问题时使用。

¥Indicative - Use when making a factual statement or question.

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

¥Example: Since there is no testing framework available, "Fastify recommends ways to write tests".

命令式 - 在给出说明、操作、命令或编写标题时使用。

¥Imperative - Use when giving instructions, actions, commands, or when you write your headings.

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

¥Example: Install dependencies before starting development.

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

¥Subjunctive - Use when making suggestions, hypotheses, or non-factual statements.

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

¥Example: Reading the documentation on our website is recommended to get comprehensive knowledge of the framework.

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

¥Use active voice instead of passive

使用主动语态是一种更紧凑、更直接的传达文档的方式。

¥Using active voice is a more compact and direct way of conveying your documentation.

示例

¥Example

被动的：节点依赖和包由 npm 安装。

¥Passive: The node dependencies and packages are installed by npm.

积极的：npm 安装包和节点依赖。

¥Active: npm installs packages and node dependencies.

写作风格

¥Writing Style

文档标题

¥Documentation titles

在 /docs/ 目录中创建新指南、API 或参考时，请使用最能描述文档主题的简短标题。使用 kebab-case 命名文件，并避免使用 Raw 或驼峰命名法。要了解有关 kebab-case 的更多信息，你可以访问有关 表壳样式 的这篇中等文章。

¥When creating a new guide, API, or reference in the /docs/ directory, use short titles that best describe the topic of your documentation. Name your files in kebab-cases and avoid Raw or camelCase. To learn more about kebab-case you can visit this medium article on Case Styles.

示例：

¥Examples:

hook-and-plugins.md,

adding-test-plugins.md,

removing-requests.md。

超链接

¥Hyperlinks

超链接应该有一个明确的标头来说明它所引用的内容。你的超链接应如下所示：

¥Hyperlinks should have a clear title of what it references. Here is how your hyperlink should look:

<!-- More like this -->

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

<!--Less like this -->

// incomplete description
[Fastify] (https://fastify.dev/docs/Plugins/)

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

// Empty title
[](https://fastify.dev/docs/Plugins/)

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

在文档中包含尽可能多的重要参考资料，但在为初学者编写时避免使用大量链接，以免分散注意力。

¥Include in your documentation as many essential references as possible, but avoid having numerous links when writing for beginners to avoid distractions.