措辞

避免使用“容易”和“仅仅”之类的词语

避免使用“容易”、“仅仅”、“简单”和“基本”之类的词语。如果用户在完成原本“容易”的任务时遇到困难，他们会质疑自己的能力，或对文档感到恼火。考虑使用更具体的描述符。例如，当你说“部署很容易”这句话时，你真正的意思是什么？是因为它比其他选项步骤更少而容易吗？如果是这样，请使用尽可能具体的描述符，在这种情况下，这将是“这种部署方法比其他选项步骤更少。”

为了使文档更具包容性，避免使用假设读者经验或技能水平的短语，例如“只需部署它就完成了”或“为了复习（当你提到某人可能没有阅读过的完全不同的文档时）”。通常，当你改述时，你会得到在更广泛的上下文中起作用的更强的句子。

避免使用拉丁术语

这些在英语中很常见，但对于非第一语言使用者来说可能会有问题。其中一些甚至会让以英语为母语的人感到困惑。

例如

避免	好
et al	“和其他人”
etc.	“等等”，或列出所有情况
i.e.	“换句话说”
e.g.	“例如”或“例如”
via	“使用”或其他等效词，例如“现在你可以开始使用生成的 Prisma Client API 发送查询”

避免使用动名词（“ing”动词形式）

避免使用动名词（动词的“ing”形式）。例如，使用“开始使用”而不是“开始使用中”。此指南适用于标题和正文。

示例

避免	好
使用浏览器测试证书	用浏览器测试证书
排除字段	排除字段
如果您正在使用 Node.js 18 或更高版本...	如果您使用 Node.js 18 或更高版本...
你可以通过重建 Prisma Client 来做到这一点	要做到这一点，请重建 Prisma Client
在设计你的模式时...	当你设计你的模式时...

请注意，以“ing”结尾的名词是可以的，例如“跟踪”。

避免在列表前使用不完整的句子

当您引入列表时，请不要使用不完整的句子。

使用

您可以通过以下方式配置模式

• 项目 1
• 项目 2

避免

你可以

• 项目 1
• 项目 2

当您引用文档的其他部分时

使用以下术语

• 页面
• 章节

记录

将数据库中的行称为记录。例如

“以下 create 查询创建一个 User 记录。”

请勿使用

• 条目
• 行
• 对象

模型属性

模型属性指的是引用模型的顶层 PrismaClient 属性

const result = await prisma.user.findMany(...) // "user" model property
const result = await prisma.post.findMany(...) // "post" model property

版本号

• 将版本号称为“x.x.x 版本”
• 当您比较版本号时，请使用“之前”和“之后”（或“更高版本”）
• 请勿使用“较低”和“较高”

<!-- Good -->

This feature is in Preview in versions 3.5.0 and later.

<!-- Bad -->

This feature is in Preview in v3.5.0 and higher.

当您编写有关特定版本时，请明确您指的是哪个产品。例如，在以下句子中，3.11.1 版本可能指的是 Prisma 或 MongoDB

此筛选器仅在 MongoDB 版本 3.11.1 及更高版本中可用。

当产品从上下文中不清楚时，请在版本号前显式提及产品名称。

此筛选器仅在 Prisma 版本 3.11.1 及更高版本中适用于 MongoDB。

在弃用通知中，请提及弃用版本号，但不提及计划删除的版本号

当您解释某个功能已弃用时，请包含其弃用的版本号。但是，计划会改变。为了使文档简洁准确，请不要提及 Prisma 计划删除该功能的版本。

<!-- Good -->

From v3.0.0, the `command name` command is deprecated.

<!-- Bad -->

From v3.0.0, the `command name` command is deprecated.
We plan to remove `command name` in v.4.0.0.

缩写术语

如果要缩写术语，请先完整写出，然后将缩写放在括号中。之后，您可以在页面的其余部分使用缩写。例如，“在计算机科学中，抽象语法树 (AST) 是……”

另请参阅：术语

避免使用模棱两可的英语单词

避免使用以下常见英语单词，因为它们对许多读者来说是模棱两可的。

要避免的单词	避免的原因	改为使用以下单词
As	可以表示“因为”或“同时”	“因为”，或“同时”，视情况而定
Since（表示“因为”）	也可以表示“之后”（如“自从你升级后”）	“因为”
May（表示“可能”）	也可以表示“允许”	“可能”
Should（表示“应该”）	也可以表示“可能会发生”	“必须”：“您必须重建 Prisma Client”，或者 省略：“重建 Prisma Client。”
Once（表示“当”或“之后”）	也可以表示“发生一次”	“当”：“当构建完成后……”
Wish（表示“想要”）	在国际上并不总是明确	“想要”

使用清晰的超链接

避免使用“单击此处”或“此处”作为链接文本。它们被认为是 Web 上的不良做法。

<!-- Good -->

Read more in the [Prisma ORM docs](/orm)

<!-- Bad -->

Read more in the Prisma ORM docs [here](/orm)

如果你的链接文本是目标页面的标题，请使用句子大小写

<!-- Good -->

For more information, see [Relation queries](/orm/prisma-client/queries/relation-queries).

<!-- Bad -->

For more information, see [Relation Queries](/orm/prisma-client/queries/relation-queries).

当链接目标显而易见时（例如，如果你在前一句中解释了概念），那么提供进一步信息的链接的一种非常简洁（且可维护）的方法如下

[Learn more](/orm/prisma-client/queries/relation-queries)

特定术语

“预览”和“正式发布”

这些使用小写。“GA”，即正式发布的缩写，使用全部大写。

<!-- Good -->

We made composite types generally available in version 3.12.0.
They were previously available in preview from version 3.10.0.

<!-- Bad -->

We made composite types Generally Available in version 3.12.0.
They were previously available in Preview from version 3.10.0.

SQL

写“一个 SQL 查询”，而不是“一个 SQL 查询”。例如：“一个 SQL 数据库……”。

macOS

好：macOS

不好：Mac OS、MacOS 或任何其他变体

终端窗口

使用术语“终端窗口”。请勿使用“命令提示符”或“shell”。例如

Open a terminal window.

设置/安装

这可以是一个名词（“安装”）或动词（“设置”），因此会造成混淆。尽量避免使用，并使用替代术语。例如，“配置”或“启用”。

如果你必须使用它，请确保使用正确的形式。记得检查代码片段，它可能潜伏在代码注释中。

关系

在指关系时，请使用以下形式

避免	好
1-1	一对一
1-n	一对多
m-n	多对多

prisma 根命令

我们经常引用 prisma CLI 命令，例如 prisma db push。

• 这些命令的长格式包括 prisma 根命令。例如：prisma db push。
• 这些命令的短格式省略了 prisma 根命令。例如：db push。

只有当用户包含 prisma 时，prisma CLI 命令才有效。在大多数情况下，请使用长格式来帮助在此时进入文档的用户。长格式还允许文档用户将可用的命令复制并粘贴到他们的终端窗口中。

在以下情况下使用长格式

• 当你在代码框中包含 prisma 命令时。
• 当你在过程中包含 prisma 命令时。

在以下情况下可以使用短格式。这有助于文档的简洁性和可读性。

• 当您讨论 prisma 命令时，例如在参考资料中。示例：“db push 使用与 Prisma Migrate 相同的引擎...”
• 当您在标题中提及 prisma 命令时。示例

所有格 's'

明确指出所有者和所有权，不要使用所有格 *s*。

当您避免使用所有格 's' 时，您还可以避免

• 将太多的名词串在一起
• 与本地化相关的问题以及国际读者对您文档的理解程度

<!-- Good -->

Change the database connection string of an environment

<!-- Bad -->

Change the environment's database connection string

输入 vs [提供，键入]

使用 *输入* 来表示填写或在文本框或输入字段中键入的操作。

不要使用 *提供* 或 *键入*。

<!-- Good -->

In **Display Name**, enter a name for your project.

<!-- Bad -->

In **Display Name**, type a name for your project.
In **Display Name**, provide a name for your project.

清除 vs [取消选择, 取消选中, 取消勾选, 取消标记]

使用 *清除* 来指导读者从复选框中删除勾选标记。

<!-- Good -->

Clear **Include sample data**.

<!-- Bad -->

Deselect the **Include sample data** checkbox.

选择 vs 选取

选取 传达了进行一般选择的概念，而 *选择* 在从选项列表中精选选项或进行 UI 选择的上下文中效果更好。

当您指导读者选择哪个 UI 选项时，使用 *选择*。

<!-- Good -->

From **Payment method**, select **Wire transfer**.

当您对选择一个选项而不是另一个选项进行概念描述时，使用 *选取*。

<!-- Good -->

You can choose to host your project in Vercel or Netlify.

复选框 vs 勾选框

使用 *复选框*。

请参阅避免过度使用 UI 术语。