Word choice

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:

Avoid	Good
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:

Avoid	Good
Test the certificate using a browser	Test the certificate with a browser
Excluding fields	Exclude 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 Client	To 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 …".

Avoid ambiguous English words

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

Word to avoid	Reason to avoid	Use the following word instead
As	Can 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"

Use clear hyperlinks

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

<!-- Good -->

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

<!-- Bad -->

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

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

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

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](/orm/prisma-client/queries/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...".

macOS

Good: macOS

Bad: Mac OS, MacOS, or any other variant

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 that you use the correct form. Remember to check in code snippets, where it might lurk in the code comments.

Relations

When referring to relations, use the following forms:

Avoid	Good
1-1	One-to-one
1-n	One-to-many
m-n	Many-to-many

The `prisma` root command

We often refer to prisma CLI commands such as prisma db push.

The long form of these commands includes the prisma root command. For example: prisma db push.
The short form of these commands omits the prisma root command. For example: db push.

prisma CLI commands only work when the user includes prisma. In most cases, use the long form to help docs users who drop into the docs at that point. The long form also let docs users copy and paste a working command into their terminal windows.

Use the long form in these circumstances:

When you include a prisma command in a code box.
When you include a prisma command in a procedure.

It is OK to use the short form in the following circumstances. This can help with brevity and readability in the docs.

When you discuss a prisma command, for example in reference material. Example: "db push uses the same engine as Prisma Migrate..."
When you mention a prisma command in a heading. Example

Possessive s

Indicate owner and ownership clearly and do not use possessive s.

When you avoid possessive s, you also avoid:

stringing together too many nouns
issues related to localization and how well international readers understand what you document

<!-- Good -->

Change the database connection string of an environment

<!-- Bad -->

Change the environment's database connection string

enter vs [provide, type]

Use enter for the action of filling out or typing in a text box or input field.

Do not use provide or type.

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

clear vs [deselect, unselect, uncheck, unmark]

Use clear to guide readers to remove the check mark from a checkbox.

<!-- Good -->

Clear **Include sample data**.

<!-- Bad -->

Deselect the **Include sample data** checkbox.

select vs choose

Choose conveys the idea of making a choice in general, while select works better in the context of fine-picking an option or making a UI selection among a list of options.

Use select when you guide readers which UI option to select.

<!-- Good -->

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

Use choose when you make a conceptual description of choosing one option over another.

<!-- Good -->

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

checkbox vs check box

Use checkbox.

See Avoid excessive use of UI terminology.

Avoid words like "easy" and "just"​

Avoid Latin terms​

Avoid gerunds ("ing" verb forms)​

Avoid incomplete sentences before lists​

Use​

Avoid​

When you refer to other parts of the docs​

Records​

Model property​

Version numbers​

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

Abbreviate terms​

Avoid ambiguous English words​

Use clear hyperlinks​

Specific terms​

"Preview" and "general availability"​

SQL​

macOS​

Terminal window​

Set up/setup​

Relations​

The prisma root command​

Possessive s​

enter vs [provide, type]​

clear vs [deselect, unselect, uncheck, unmark]​

select vs choose​

checkbox vs check box​