Avoid words like "easy" and "just"

Avoid words like "easy", "just", "simple", and "basic". If users have a hard time completing the task that is supposedly "easy," then they will question their abilities, or get aggravated by the docs. Consider using more specific descriptors. For example, when you say the phrase "deployment is easy," what do you really mean? Is it easy because it takes fewer steps than another option? If so, use the most specific descriptor possible, which in that case would be "this deployment method involves fewer steps than other options."

For even more inclusive docs, avoid phrases that assume a reader’s experience or skill level, like "just deploy it and you’re done" or "for a refresher (when you refer to a completely different doc that someone might not have read)". Often, when you rephrase, you get stronger sentences that work in a wider range of contexts.

Avoid Latin terms

These are common in English, but can be problematic for non-first-language speakers. Some of them can be confusing even to native English speakers.

For example:

AvoidGood
et al"and others"
etc."and so on", or list all of the cases
i.e."in other words"
e.g."such as" or "for example"
via"with" or other equivalent, as in "Now you can start to send queries with the generated Prisma Client API")

Avoid gerunds ("ing" verb forms)

Avoid gerunds (the "ing" form of verbs). For example, use "Get started" instead of "Getting started". This guideline applies to headings and body text.

Examples:

AvoidGood
Test the certificate using a browserTest the certificate with a browser
Excluding fieldsExclude fields
If you are using Node.js version 18 or later...If you use Node.js version 18 or later...
You can do this by rebuilding Prisma ClientTo do this, rebuild Prisma Client
When designing your schema...When you design your schema...

Note that nouns ending in "ing" are fine - for example "Tracing".

Avoid incomplete sentences before lists

When you introduce a list, do not use an incomplete sentence.

Use

You can configure your schema in the following ways:

  • Item 1
  • Item 2

Avoid

You can:

  • Item 1
  • Item 2

When you refer to other parts of the docs

Use the following terms:

  • Page
  • Section

Records

Refer to rows in the database as records. For example:

"The following create query creates a single User record."

Do not use:

  • Entry
  • Row
  • Object

Model property

Model property refers to the top-level PrismaClient properties that refer to models:

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

Version numbers

  • Refer to version numbers as "version x.x.x"
  • When you compare version numbers, use "before" and "after" (or "later")
  • Do not use "lower" and "higher"
<!-- 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.

When you write about a specific version, make it clear what product you are referring to. For example, in the following sentence, version 3.11.1 might refer to Prisma or to MongoDB:

This filter is available for MongoDB only in versions 3.11.1 and later.

When the product is not clear from the context, explicitly mention the product name in front of the version number.

This filter is available for MongoDB only in Prisma versions 3.11.1 and later.

In deprecation notices, mention the deprecation version number but not the planned removal version number

When you explain that a feature is deprecated, include the version number in which it was deprecated. However, plans change. To keep docs lean and accurate, do not mention the version in which Prisma plans to remove the feature.

<!-- 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.

Abbreviate terms

If you want to abbreviate a term, write it out fully first, then put the abbreviation in parentheses. After that, you can use the abbreviation for the rest of the page. For example, "In computer science, an abstract syntax tree (AST) is …".

See also: Jargon

Avoid ambiguous English words

Avoid the following common words in English, because they are ambiguous to many readers.

Word to avoidReason to avoidUse the following word instead
AsCan mean "because" or "at the same time as""Because", or "At the same time", as appropriate
Since (to mean "because")Can also mean "after" (as in "since you upgraded")"Because"
May (to mean "might")Can also mean "is permitted to""Might"
Should (to mean "ought to")Can also mean "might happen""Must": "You must rebuild Prisma Client", or
Omit: "Rebuild Prisma Client."
Once (to mean "when" or "after")Can also mean "happens once""When": "When the build completes..."
Wish (to mean "want")Not always clear internationally"Want"

Avoid the constructions "click here" or "here" for link text. They are considered bad practice on the web.

<!-- Good -->
Read more in the [Prisma docs](https://www.prisma.io/docs/)
<!-- Bad -->
Read more in the Prisma docs [here](https://www.prisma.io/docs/)

If your link text is the title of the destination page, use sentence case:

<!-- Good -->
For more information, see [Relation queries](/concepts/components/prisma-client/relation-queries).
<!-- Bad -->
For more information, see [Relation Queries](/concepts/components/prisma-client/relation-queries).

When it is obvious what the link destination is (for example if you've explained the concept in the preceding sentence), then a very concise (and maintainable) way to provide a link to further information is as follows:

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

Specific terms

"Preview" and "general availability"

Use lower case for these. For "GA", the abbreviation of general availability, use all caps.

<!-- 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

Write "a SQL query", not "an SQL query". Example: "A SQL database...".

Terminal window

Use the term "terminal window". Do not use "command prompt" or "shell". Example:

Open a terminal window.

Set up/setup

This can be a noun ("setup") or verb ("set up") and as such can cause confusion. Try to avoid, and use an alternative term. For example, "configure" or "enable".

If you must use it, ensure you use the correct form. Remember to check in code snippets, where it might lurk in the code comments.

Other terms

We have an internal terminology page. When we have agreed on these, we will add them to this page.

Edit this page on GitHub