如何从文档中删除居高临下的语言

受到Anjana Vakil 的一条推文的启发，我为 Hacktoberfest 2019 设定了一个目标，从开源文档中删除诸如 或任何其他变体之类的词语simple。easy

在接下来的一个月里，我向Jest、Cypress、Storybook等项目，甚至 Meeshkan (🙈) 的一些代码库提交了十几个 Pull Request。这项举措也启发了webpack、Tailwind CSS和React Native 的Pull Request。React Native 团队甚至更进一步，在 30 位外部贡献者的帮助下，在 6 天内完成了其文档全部 56 个版本的 lint 工作。

在这个过程中，我深刻体会到创建更具包容性的文档的价值，以及实现它的实用性。因此，我将这些经验总结成了一份指南！

目录

• 为什么要关注居高临下的语言？
• 什么是居高临下的语言？
• 正如承诺的那样，有导游！
• 最后，谢谢你🎉

为什么要关注居高临下的语言？

React Native 团队的 Rick Hanlon在最近的一条推文中很好地总结了这一点：

当我们说事情“容易”或“简单”时，如果人们不能立即理解，他们就会感到不足或受到伤害。

语言是主观的——对一个人来说简单的概念对另一个人来说未必简单。通过禁止文档中使用居高临下的词语，我们正在积极采取措施，使我们的资料更具包容性。

如果您对此主题感兴趣或想了解更多信息，我强烈建议您观看Jim Fisher在 2018 年布拉格编写文档大会上的演讲“不要简单地说” 。

什么是居高临下的语言？

一些被认为是居高临下的语言的例子包括……

simply
easy
basically
clearly
everyone knows
just
obviously
of course

如果您对为什么这些词被认为是居高临下的感兴趣，retext-equality（检查不敏感语言的插件）有一个带有解释性注释的完整列表。

正如承诺的那样，有导游！

⚠️ 先决条件：

• 下载并安装 Node.js 和 npm
• 您希望其文档更具包容性的开源项目

✅步骤：

1. 打开一个问题来描述你的使命
2. 使用 alex.js linter 标记居高临下的术语
3. 删除或替换居高临下的语言
4. 创建包含您建议的更改的拉取请求

1. 打开一个问题来描述你的使命

如果您不是该项目的定期贡献者，我建议您在开始任何工作之前先创建一个问题 (Issue)。如果您是开源新手，GitHub 上提供了创建问题的分步文档。

此步骤并非总是必要的，但它确实为您提供了描述此类更改将带来的价值的机会，并了解维护人员是否愿意接受这种类型的更改（并非所有人都愿意）。

另一方面，这允许维护人员为更改建议一种首选格式 - 例如，为每个部分提交一个拉取请求而不是一次提交所有请求 - 并让您知道他们是否有任何您可以使用或修改的现有语言 linters。

参考：我在 Cucumber 文档上提出的一个问题。

2. 使用 alex.js linter 标记居高临下的术语

你已经获得了维护人员的同意。你也已经 fork 并克隆了代码库。现在，你需要找出那些可能被移除的、带有傲慢意味的术语。

您可以在文档中手动搜索术语……但这很繁琐。而且，您更有可能错过变体（例如，easily而不是easy）或您不知道的冒犯性词语。因此，为了提供帮助，我建议使用alex.js。

alex.js 是一款开源语言代码检查工具，旨在捕捉 Markdown 文件中那些带有两极化倾向的语言，并提出实用的替代方案。由于其规则植根于retext-equality，alex 能够标记出我们需要移除的傲慢语言，以及残疾歧视、性别歧视、恐同、种族歧视等语言，以及其他任何最好从文档中删除的语言。

要使用 alex 对开源文档进行 linting，您可以采用两种方法：

npx alex在 repo 目录中运行

使用npx允许您运行 linter，而无需将 alex 安装为项目依赖项。我建议将此作为第一步，因为根据经验，要求维护人员添加额外的依赖项比更改文档中的措辞更具说服力。

要在本地运行 alex，请使用终端进入包含要进行 lint 的 Markdown 文件的目录。在许多项目中，此文件夹名为docs/。进入该目录后，运行以下命令：

npx alex

您还可以通过在命令末尾添加文件名来检查特定文件。在此示例中，我们正在检查项目的README.md文件：

npx alex README.md

将 alex 安装为项目内的依赖项

如上所述，这一点可能需要更多的前期说服 - 但如果一个项目致力于将这种类型的语言排除在他们的文档之外，那么这是他们可以采取的主动步骤。

要在项目工作流程中设置 Alex，您可以按照此分步教程进行操作。由于这需要额外的配置，维护人员可能会要求您在单独的拉取请求中处理此问题。

3. 删除或替换居高临下的语言

尽管这很诱人，但您肯定不想删除所有 Alex 或您自己的搜索标记的条目。因为有时，这些词条的存在可能是出于必要，或者是为了显得更受欢迎。

在进行任何更改之前，请查看每个实例并询问以下问题...

这是否真的是一种屈尊俯就或冒犯的表现？

例如，像 这样的词simple可以用来描述特定类型的网络协议，或者 Alex 会标记出 像 这样的术语，host这些术语可能指代网络主机。所以，你需要确保没有删除或修改那些对理解至关重要的术语。

有必要吗？

just很多情况下，这些带有居高临下意味的词语都是副词，可以直接删除，无需替换。我发现“和”这两个词尤其如此of course。

如果有必要，它想表达什么？

在文档中，很少有术语easy故意显得居高临下。很多时候，作者会用它们来表明某些东西并不像听起来那么吓人。如果是这样，请思考文档想要传达什么，并用更能表达意图的词语来替代那些居高临下的语言。

如果您正在努力寻找替代方案，Jim Fisher 有一些建议：

• 具体一点：也许它很容易，因为它设置起来很快，不需要太多的输入或者只有很少的活动部件。
• 具有可比性：某物比其他物小。与其他产品相比，您的产品需要的定制配置更少。
• 绝对：集成此库只需 5 行代码。需要两个表单字段。
• 展示，而不是讲述：不要使用时间来指示某件事有多容易，而是制作视频。

4. 创建包含你提议的更改的拉取请求

现在工作已完成，您可以通过拉取请求 (pull request) 提出您的更改。如果您是开源新手，GitHub 提供了有关创建拉取请求 (pull request) 的分步文档。

请务必遵循项目的贡献指南，并引用您最初的问题（如果您创建过）。即使您引用的是问题，也请包含以下内容：

• 您希望通过此拉取请求实现的目标的摘要
• 在问题中达成的任何协议
• 您删除或替换的术语示例

这样，如果另一个维护者审查您的更改，他们就可以获得背景信息，而无需阅读整个问题和讨论。

参考：我为 Prisma 创建的拉取请求。

最后，谢谢你🎉

感谢您花时间阅读本指南，并致力于打造更具包容性的开源文档！我们需要更多像您这样优秀、充满爱心的人。这项工作也需要提升公众意识。因此，我鼓励您与同事、朋友、Twitter 粉丝以及任何愿意倾听的人分享您的心路历程。