跳转到主要内容

写作风格

受众

我们假设受众具备基本的软件开发知识。我们的受众知道如何使用他们的工具,例如他们的 IDE 和终端窗口。我们的许多用户都熟悉高级软件开发概念和技术,但我们不能在文档中假设这一点。我们不能假设用户具备任何数据库知识。

简化

尽可能简单地写作是技术交流的一个良好原则。这比听起来要难,但额外的努力是值得的,它可以使文档更清晰、更易读。当你为全球受众写作时,这一点尤其重要,因为他们并非都精通英语。

  • 使用短段落
  • 坚持使用简短的句子。尽可能避免使用多个从句的句子。
  • 英语有很多同义词 - 尽可能选择最简单的词来完成工作。示例:“in”而不是“within”,“use”而不是“utilize”。
  • 使用项目符号列表将复杂的句子分解为组成要点
  • 使用示例
  • 使用适当的文本强调,例如粗体和斜体,使你的写作更清晰
  • 使用表格来列出复杂的信息
  • 使用图表使复杂的工作流程或概念更容易可视化

语气

以冷静、自信的语气写作。我们的语气友好且直接,但我们不使用俚语

使用美式英语写作

美式英语是全球公认度最高的英语形式。使用美式英语的标点符号、语法和拼写。例如

  • color 而不是 colour
  • behavior 而不是 behaviour
  • Prisma plans to 而不是 Prisma plan to

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

避免使用表情符号、习惯用语、俚语和隐喻。Prisma 拥有一个全球社区,这些项目的文化含义在世界各地可能不同,并且会随着时间而变化。

避免使用诸如“it”或“that”之类的模糊代词

当您指代特定的名词时,请尽量具体。除非您在上一句话或从句中刚刚定义了该专有名词,否则请勿将该名词称为“it”。即便如此,如果再次指定名词,您的写作对于国际受众来说可能会更清晰。特别是,避免以“It”开头句子。

使用第二人称写作

第二人称(“你”)给人一种对话的语气,并直接与读者对话。避免使用第一人称(“我”、“我们”、“让我们”和“我们”)。示例

“你必须将整个 prisma/migrations 文件夹提交到源代码控制。”

例外:当您指代 Prisma 组织时,请使用“我们”。例如,此处 Prisma(组织)建议采取一项行动

“我们建议您在整个应用程序中共享 PrismaClient 的单个实例。”

使用包容性语言

当您用第三人称指代一个人或多个人时,请使用包容性的、性别中立的语言。使用“他们/她们/他们的”代替“他/他的/他的”或“她/她的/她的”。避免使用诸如“guys”之类的特定性别的词。

行话

行话:(n.) 特定行业或群体使用的特殊词汇或表达方式,其他人难以理解。

Prisma 文档包含大量技术细节,行话是不可避免的。但是,我们努力尽可能少地使用行话。

当您使用行话时,请遵循以下准则

  • 如果您可以用几句话解释行话,那么您可能更愿意在那里解释它。请自行判断这是否对本文档最有利。

  • 对于较长的解释,请链接到其他地方的定义。

    • 如果该行话是 Prisma 特有的,则链接到我们文档中的定义。

    • 如果该行话不是 Prisma 特有的,请检查是否可以通过网络搜索快速找到定义。如果是这样,则不要解释该术语或链接到定义。我们可以合理地期望用户知道该行话或自己找到解释。

  • 仅在文档的逻辑部分中第一次出现行话术语时进行链接。

    逻辑部分是指我们可能期望某人一次阅读的文档部分。通常,它是页面,或包含一个或多个标题部分的页面的独立部分。

  • 当您链接到外部定义时,请选择可信的来源。维基百科是可以接受的,官方第三方文档更好。

使用主动语态

使用主动语态而不是被动语态。这是一种更简洁、更直接的交流方式。例如

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

当我们的软件或第三方软件执行某些操作时,如果这对用户很重要,请说明哪个模块或组件执行该操作。

  • “Prisma Client 将所有 DateTime 返回为 ISO 8601 格式的字符串。”

如果模块或组件对用户不重要,则说 Prisma(或第三方软件的名称)执行该操作

  • “Prisma 在查找环境变量时会从系统环境中读取...”
  • “这是因为 MongoDB 返回的游标附加到您的 MongoDB 会话...”

有时,您可以完全省略操作组件或模块

  • “请参阅 /directoryX 中的生成的日志文件。”

自信

使用自信的语言。

  • 使用 createMany 方法在单个事务中创建多个记录
  • 您可以使用嵌套写入来同时创建用户和该用户的帖子

避免

  • 此示例尝试...
  • 你可能可以...
  • 您可以使用...

程序中的自信语言

  • 安装 dotenv-cli

避免

  • 请安装 dotenv-cli

使用“that”来阐明句子

示例:“确保重建你的模式。”。

请参阅:“That”作为名词从句的连词

使用一般现在时

  • 使用一般现在时写作。
  • 即使你想写一些会因用户操作而发生的事情,也请使用一般现在时:说结果会发生,而不是说它将会发生。
<!-- Good -->

When you run this command, Prisma writes the following log file.

<!-- Bad -->

When you run this command, Prisma will write the following log file.

指示何时某项是可选的

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

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

对于程序中的可选步骤,简洁地传达这一点的方法是在步骤前加上“可选:”。例如

  1. 可选:在“标签”字段中,为您的文件指定一个或多个标签。用逗号分隔多个标签。

代码示例

所有查询示例都以常量开头。这样可以在文档后面引用一个名词,并且在大多数情况下,这可以使示例更清晰。

示例

const aggregations = await prisma.user.aggregate({
...
})