Gatsby 风格指南

欢迎！

你不必是某个主题的专家才能写它——整个网站都是开源的，所以即使你犯了错误，在 PR 合并之前，其他贡献者也会帮助你修正。

在开始写作之前，请确保阅读本风格指南的其余部分。

我能写哪些类型的文档？

请参阅 文档结构，了解不同类型文档的概览以及格式化指南。

写作流程

考虑你的受众

在开始写作之前，请回答这些问题。已包含示例答案

问题：谁会阅读我的文章？ 答案：熟悉 HTML、CSS 和 JS 但不一定熟悉 React 或 GraphQL 的开发者。

问题：我希望我的读者在阅读后能够知道和/或能够做什么？ 答案（示例）：我希望我的读者能够在他们的 Gatsby 网站上成功添加搜索功能。

回答完这些问题后，创建一个主题大纲，并考虑将使用的任何代码示例（如果适用）。这有助于整理思路，使写作过程更加轻松。

研究

很多时候，你的文档需要的信息已经存在于某处。

避免复制粘贴大量他人的作品。相反，使用他们的作品来学习，以便你能写出自己的文档。如果你确实逐字引用了某人的作品，请注明信息来源。

如果内容已在网站的其他地方存在，可以随意复制粘贴，无需引用或注明来源。

可能的优秀研究材料来源

• 博客文章（在 gatsbyjs.com 和其他网站上）
• 文档（在 gatsbyjs.com 和其他网站上）
• 视频教程
• Discord 或 Twitter 对话
• 搜索引擎结果
• 你或其他人的演讲
• 教科书
• 梦境
• 任何你能想到的其他内容

撰写草稿并获取反馈

技术写作，即科学和技术的文献，之所以困难，是因为它要求你将技术性（通常是抽象的）主题以清晰、准确和客观的方式进行解释。在你满意你的写作之前，你很可能需要经过几轮校对和编辑。

此外，还有一个贡献者社区在支持你。在 Gatsby Discord 和 GitHub 仓库 中与他们交流想法并征求对你写作的意见。

词语选择

使用“你”作为代词

在英语中，你的文章应使用第二人称（“你”）来提供对话的语气。这样，文本和说明似乎直接与阅读者对话。尽量避免使用第一人称（“我”、“我们”、“让我们”和“我们”）。

对于其他语言，请参考各翻译的指南（如果适用）以获得一致的措辞。在适当的情况下，我们建议使用非正式的“你”来保持对话的语气。

在英语中使用“你”也比说“我们”更准确，因为通常一次只有一个读者在阅读教程或指南，而撰写教程的人实际上并没有和他们一起进行，所以“我们”会不准确。你可能会注意到，一些技术文档使用第三人称代词和名词，如“他们”和“用户”，这增加了距离感，比对话式和温暖的“你”和“你的”感觉更冷。

在更新文档以符合 Gatsby 风格指南的这一部分时，英语中的一个例外是当“我们”指代 Gatsby 的核心流程时。在这种情况下，主语是代码，而不是老师/读者含义，应重写或重组，以免读者混淆后台自动发生的事情以及他们需要做什么。

避免使用“容易”和“简单”

避免使用“容易”、“简单”和“基础”等词语，因为如果用户在完成所谓“容易”的任务时遇到困难，他们会质疑自己的能力。考虑使用更具体的描述符；例如，当你说的“部署很容易”是什么意思？如果它比其他选项需要更少的步骤，那么它就容易吗？如果是这样，请使用尽可能具体的描述符，在这种情况下，“这种部署方法比其他选项步骤更少。”

为了让文档更具包容性，避免使用假设读者经验或技能水平的短语，如“只需部署即可完成”或“为了复习（指某人可能未读过的完全不同的文档）”。通常，重新措辞会产生更强大的句子，从而吸引更广泛的背景。

避免使用表情符号、俚语和隐喻

在文档中避免使用表情符号或笑脸符号，以及习语/俚语或隐喻。Gatsby 是一个全球社区，表情符号、笑脸符号或俚语的文化含义在世界各地可能有所不同。请自行判断！此外，表情符号在不同系统上的显示效果可能不同。

定义术语

文章应使用简短、清晰的句子撰写，并尽量少用术语。

术语：（名词）特定职业或团体使用的、他人难以理解的特殊词语或表达：法律术语。

所有术语都应立即用通俗的英语进行定义。换句话说，假装你的读者具有基本的编码经验，但不一定具有 PWA 和 JAMstack 的经验（看到这里发生了什么吗？我刚用了两个需要定义的术语）；你需要定义新来者可能难以理解的词语。

写作风格

简洁写作

简洁的写作以最少的冗余传达最少的信息。努力使你的写作尽可能简短；这种做法通常会导致更准确和具体的写作。

使用清晰的超链接

超链接应包含最清晰的词语来指示链接将带你到哪里。为了可访问性，应避免在超链接上使用 title 属性。

在针对初学者的教程中，尽量少使用超链接以最大程度地减少干扰。在文档中，可以包含尽可能多的超链接来提供相关和有趣的信息和资源。

对本地链接使用相对超链接

在引用 gatsbyjs.com 上的另一个页面时，超链接应使用相对路径（不包含完整域名）。这确保了所有链接在本地运行或在预览中都能正常工作。

将 localhost URL 标记为代码字符串

除非你在本地运行 gatsby develop 或 gatsby build，否则 localhost 链接将无法正常工作。因此，建议将这些 URL 引用列为代码块，以免文档中出现无效链接。

标明内容何时为可选

当一个段落或句子提供了一个可选路径时，第一个句子的开头应标明它是可选的。例如，“如果你想了解更多关于 xyz 的信息，请参阅我们的参考指南”比“如果你想了解更多关于 xyz 的信息，请转到参考指南”更清晰。

这种方法允许那些 不想 了解更多关于 xyz 的人尽早停止阅读句子。这种方法也允许那些 想 了解更多关于 xyz 的人更快地认识到学习的机会，而不是意外地跳过段落。

缩写术语

如果你想在文章中缩写一个术语，先完整写出它，然后将缩写放在括号里。之后，你可以在文章的其余部分使用缩写。例如，“在计算机科学中，抽象语法树（AST）是……”

使用 SEO 优化标题

这解释了如何考虑搜索引擎优化（SEO）并创建一个在 Google 或 Bing 等搜索引擎中显示的文档。

当你创建 `/docs/` 下的新指南或教程时，如果文档中将包含图片，你将创建一个文件或一个文件夹。

文件： querying-data-with-graphql.md

或

文件夹： querying-data-with-graphql querying-data-with-graphql/index.md querying-data-with-graphql/graphql-image.png

.md 标题或文件夹标题会自动转换为 URL 路由。

文章标题应简短并反映文章的主题，以帮助读者快速找到相关信息。许多人使用搜索引擎查找“gatsby GraphQL”之类的主题，因此文章标题最好能反映常见的搜索词。

以下是一些标题示例

• 创建与修改页面
• 添加 404 页面
• 使用 GraphQL 查询数据

文件夹名称用于 URL，因此只使用连字符 -、数字 0-9 和小写字母 a-z。

以下是一些文件夹名称示例

• creating-and-modifying-pages
• adding-a-404-page
• querying-data-with-graphql

注意：需要澄清的是，你可以在文章标题中包含特殊字符，但在 .md 文件名或文件夹名称中 不能 包含（例如，标题：What is GraphQL？，文件夹名称：what-is-graphql）。

语法和格式

格式化标题和副标题

文章标题使用标题大写（每个主要单词首字母大写）。文章标题使用句子大写（只有首字母大写）。两者末尾都不需要标点符号，除非需要问号。文章标题不使用牛津逗号，而是使用“&”代替“and”。文章标题使用牛津逗号，并使用“and”一词。

标题自动格式化为 h1。将文章标题标记为 h2，将副标题标记为 h3 或 h4。大多数文章标题在概念和修辞上处于同一级别；避免不必要的复杂性，除非它们是真正的副标题，否则将其标记为 h2。

文章标题或文档标题

咸、甜与辣

文章头或副标题

咸、甜与辣

标题应力求简短，同时传达文章的全面含义；标题在长度上有更大的灵活性。因为标题会显示在文档的导航元素中（如面包屑导航和侧边栏导航），所以偏好使用较短的名称以减少视觉混乱。

格式化代码块、行内代码和图片

创建和编辑文档时，请使用以下内容作为参考

• 格式化行内代码和代码块
• 在文章中添加图片。如果图片尚未托管在网络上的其他地方，你需要自己将其在线。一种好的方法是将其提交到你自己的 GitHub 仓库，然后推送到 GitHub。然后你可以右键单击图片并复制其图片来源。别忘了为可访问性添加图片 alt 文本！有关撰写有效屏幕阅读器文本的帮助，请参阅 W3C 的决策树。
• 标题格式化。避免使用 H1 标题；该标题保留给每个文档的标题。

代码格式：行内代码

确保变量、组件名称、函数名称和出现在行内的包都用反引号进行转义。

代码格式：标签页

每个代码片段都将包含一个标签页，显示片段包含的语言类型。例如，以下 YAML 片段将显示一个“YAML”标签页……

……如下所示

请在适当的地方使用以下语言关键字

• javascript 或 js
• jsx
• graphql
• html
• css
• shell
• yaml
• markdown
• diff
• flow

如果省略了语言关键字，类型将显示为 TEXT（如上所示）。

代码格式：标题

在适当的情况下，为代码块添加代码标题。在文档的整个过程中切换多个文件会使一些读者感到困惑。最好明确告知他们代码示例应该放在哪里。你可以像往常一样使用语法高亮，然后为其添加 :title=your-path-name。使用方法如下

然后它将显示为

代码格式：行高亮

你也可以选择在代码片段中包含行高亮，使用以下关键字作为片段中的内联注释

highlight-line：高亮当前行

highlight-next-line：高亮下一行

highlight-start & highlight-end：高亮一个范围

正确使用专有名词大写

在可能的情况下，专有名词应使用正确的首字母大写。以下是在本网站的博客文章、文档和其他学习材料中应使用的单词列表。

• Gatsby
• GraphQL
• JavaScript (单词“J”和“S”使用大写字母，不允许缩写)
• TypeScript
• WordPress
• Markdown
• Node.js
• webpack (单词应始终使用小写字母，除非它出现在句子的开头)

全栈开发人员（作为形容词时带连字符）从事全栈工作（作为名词时不带连字符）。许多其他复合词也遵循此规则。

对于形容词和名词形式，均使用“frontend”，因为它更常用且易于维护。例如，a frontend developer works on the frontend。后端（backend）也遵循此规则。

“End users”拼写成两个单词，而不是用连字符连接。

使用主动语态

请使用主动语态而非被动语态。通常，这是更简洁、更直接的沟通方式。例如：

• (被动语态) JavaScript 中的 for 循环被程序员用来……
• (主动语态) 程序员使用 JavaScript 中的 for 循环来……

使用牛津逗号使列表更清晰

除非在标题中，否则请使用牛津逗号。牛津逗号是在三个或更多项目的列表的倒数第二个项目之后，在“and”或“or”之前使用的逗号。例如：an Italian painter, sculptor, and architect。它使内容更清晰。

优先使用美式英语

对于有多种拼写方式的单词，请优先使用美式英语单词，而不是英式或加式英语。例如：

• color 而不是 colour
• behavior 而不是 behaviour

使用有助于编辑的应用程序

使用 Hemingway App。这个工具没有神奇之处，但它可以自动检测公认的风格问题：

• 被动语态
• 不必要的副词
• 有更常见替代词的词语

Hemingway App 会为你的写作分配一个“年级水平”。你应该以 6 年级水平为目标。另一个可用的工具是 De-Jargonizer，它最初是为科学交流设计的，但可能有助于避免过度专业化的措辞。

最佳实践

引用 Gatsby Cloud

Gatsby Cloud 是 Gatsby 产品，专注于构建和托管 Gatsby 网站。OSS 文档的各个部分可能受益于指向 Gatsby Cloud 作为潜在的探索平台。

这样做的指导方针如下：

• 如果可能，Gatsby Cloud 应与其他相关技术一起提及。
• 如果 Gatsby Cloud 默认执行某项操作，文档仍应包含访问该功能的说明。

这些指南的目的是确保用户了解运行 Gatsby 网站的多种选择。除了 gatsby-cli 之外，开源文档通常应避免对技术选择做出假设。

支持软件版本

当 Gatsby 承诺支持特定版本的软件（例如 Node 8 及更高版本）时，这会在文档中得到体现。Gatsby 文档应可供所有受支持软件的用户使用，这意味着我们不会引入任何无法供我们承诺支持的版本用户使用的命令或实践。在极少数情况下，我们会考虑将新引入的命令或实践作为附注提及。

尽可能分享最佳实践

当有多种完成任务的方法时，文档应解释以下内容：

1. 完成任务最基本的方法
2. 完成任务最常用的方法
3. 在最低支持版本软件上完成任务的最佳方法
4. 最佳实践及其原因（如果与第 3 点不同）
5. 关于如何选择选项的任何提示

例如，gatsby-plugin-image 是一个包含 Gatsby 处理图像最佳实践的组件，但也有更基本和常用的处理方法。文档应在说明最常用和最基本的方法的同时，也明确最佳实践。

文档

在 Gatsby 中，“Docs”通常指 gatsbyjs.com/docs 下的所有内容。

文档受众

各个技能水平的开发者都会阅读文档，并发现其有用。

文档应侧重于帮助具有以下属性和目标的用户的。

属性

• React 中级到高级水平
• 前端开发人员
• 倾向于使用搜索引擎和/或 ctrl + f 在 gatsbyjs.com 网站上查找内容

正在寻找

• 快速启动并运行网站的方法
• 一种快速获取 API 正确的单词、类型、默认值、描述、参数和返回值的途径
• 用于学习和/或复制的源代码片段
• 高级任务的分步教程
• 深入理解 Gatsby 的工作原理，以至于他们可以修改或定制自己的项目，或为 Gatsby 核心做出贡献
• Gatsby 如何真正与 Redux、React 和 GraphQL 一起工作？
• 错误消息，告知他们是否是已知错误/问题，将他们引导至文档，以及/或建议修复方法
• 关于 Gatsby 中事物如何工作的指南
• 他们通常已经对他们想使用什么 CMS 或数据源有强烈的看法或要求，并希望了解他们工作流程的最佳实践
• Gatsby 是一个可靠的、长期的选择的迹象（增长和改进的迹象，以及证明它将长期存在的证据）
• 检查其项目需求与 Gatsby 提供的内容的方法
• 来自精心构建的示例网站的开源代码

文档目的

通过参考文档，用户应该能够：

• 尽快完成任务
• 评估尽可能快速完成任务的选项
• 尽快构建网站和应用程序，包括以下类型的网站：
  • 营销
  • 博客
  • 作品集
  • 电子商务
  • 身份验证
  • 可访问

文档语气和风格

文档的语气和风格应能有效地帮助受众实现其目标。

使用第一人称“你”

文档使用第一人称“你”来称呼用户。

为专家提供尽可能多的相关信息，以便他们能够尽快完成任务

由于文档的受众是具有 React 中级到专家级别掌握程度的人，因此提供完成任务所需的信息，以及所有相关且有用的上下文、参考和替代方案非常重要。目标是：为人们提供尽可能快速有效地完成任务所需的信息。

在实践中，可以通过两条通用规则来实现这一目标：

• 在每个指南的底部包含一个“附加信息”部分，其中包含指向相关外部博客文章、教程和其他 Gatsby 资源和文档的超链接。
• 当有多种完成任务的方法时，请遵循这些说明。

为什么我们选择 GitHub 来编写和维护文档

Gatsby 社区维护文档和教程的方式必须满足以下要求：

• 能够快速发布
• 能够快速迭代
• OSS 贡献者访问权限
• 代码编辑功能
• 版本控制
• 一种对每个文档提供反馈的方式

GitHub 满足这些要求。