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.
|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.
|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.
You can configure your schema in the following ways:
- Item 1
- Item 2
- Item 1
- Item 2
When you refer to other parts of the docs
Use the following terms:
Refer to rows in the database as records. For example:
create query creates a single
Do not use:
Model property refers to the top-level
PrismaClient properties that refer to models:
const result = await prisma.user.findMany(...) // "user" model propertyconst result = await prisma.post.findMany(...) // "post" model property
- 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.
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 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 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:
"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.
Write "a SQL query", not "an SQL query". Example: "A SQL database...".
Bad: Mac OS, MacOS, or any other variant
Use the term "terminal window". Do not use "command prompt" or "shell". Example:
Open a terminal window.
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.
When referring to relations, use the following forms:
prisma root command
We often refer to
prisma CLI commands such as
prisma db push.
- The long form of these commands includes the
prismaroot command. For example:
prisma db push.
- The short form of these commands omits the
prismaroot command. For example:
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
prismacommand in a code box.
- When you include a
prismacommand 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
prismacommand, for example in reference material. Example: "
db pushuses the same engine as Prisma Migrate..."
- When you mention a
prismacommand in a heading. Example
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.
We have an internal terminology page. When we have agreed on these, we will add them to this page.