写作风格
受众
我们假设受众具备基本的软件开发知识。我们的受众知道如何使用他们的工具,例如他们的 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 的信息的人更快地认识到学习的机会,而不是意外地跳过该段落。
对于程序中的可选步骤,简洁地传达这一点的方法是在步骤前加上“可选:”。例如
- 可选:在“标签”字段中,为您的文件指定一个或多个标签。用逗号分隔多个标签。
代码示例
所有查询示例都以常量开头。这样可以在文档后面引用一个名词,并且在大多数情况下,这可以使示例更清晰。
示例
const aggregations = await prisma.user.aggregate({
...
})