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.
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 (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".
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
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 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"|
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:
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...".
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 you use the correct form. Remember to check in code snippets, where it might lurk in the code comments.
We have an internal terminology page. When we have agreed on these, we will add them to this page.