Spelling, punctuation, and formatting

UI elements

For the names of GUI elements (buttons, drop-down menus, and so on), use bold. Also use the same capitalization as in the GUI. For example:

1. In the File menu, select Open....

Avoid exclamation points

In keeping with our calm tone, do not use exclamation points (exclamation marks). Exception: they are acceptable in congratulatory or welcome messages, for example: "Congratulations - you've completed the tutorial!"

Capitalize and spell out proper nouns

Although you might be tempted to use abbreviations like "Postgres" (instead of the official proper noun "PostgreSQL") or not worry about casing when writing "Javascript" (instead of "JavaScript"), we use the official forms of proper nouns. A few common examples are:

• Node.js (instead of Node or Node.JS)
• JavaScript and TypeScript (instead of JavaScript and Typescript or JS and TS)
• PostgreSQL (instead of Postgres or Postgresql)
• MongoDB (instead of Mongo)
• GitHub (instead of Github)
• For JSON, see Special case: JSON

If you're not sure about the spelling of a proper noun, check its official web site.

Titles and headings

• Use sentence case for titles and headings: only the initial word is uppercase (exception: capitalize proper nouns)
• Avoid gerunds ("Configure the database", not "Configuring the database")
• Do not use punctuation at the end of a title or heading unless a question mark is required
• Use <inlinecode>code</inlinecode> for code in headings - this is required by our navigation elements

Spell without a hyphen

• Use case
• Command line (when referring to it as a noun: "On the command line". Use a hyphen when it's an adjective: "This command-line option...")
• Auto format
• Type safety (see below for guidelines on "type safe")
• File name
• Compile time (when you use it as a noun: "... at compile time". Use a hyphen when it's an adjective: "This compile-time operation...")

Spell as one word

• Autocomplete
• Codebase

Type-safe, type safe, and type safety

• "The code is type safe." (adjective after the noun)
• "This is type-safe code." (adjective before the noun)
• "A key feature of Prisma ORM is type safety." (noun)

Data source and datasource

• The datasource block
• "You must regenerate Prisma Client when you introduce a new data source"

Special case: JSON

• When you refer to JSON in general, use all caps and no code format
• When you refer to the Prisma Json API, use Json
• When you refer to a JSON file, use the formatting rules above: "a .json file"

Use inline code format for paths and file names

For example:

• "The generated Prisma Client is located in the ./node_modules/.prisma folder by default."
• "The schema.prisma file is located in..."
• "To use multiple .env files..."

Introduce all code snippets

Write a short introductory sentence that:

• Explains what the code snippet does
• Links to reference documentation if applicable

For example:

This createMany query does the following:

• Creates several User records
• Creates several nested Post records
• Creates several nested Category records

Show the result of a query wherever possible

Use the <CodeWithResult> component to show a query and the results of that query.

Use the highlight property to highlight

Use the highlight property if you need to highlight your code samples. For example:

```prisma highlight=3;normal
generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["namedConstraints"]
}
```

Format code blocks and inline code

Use the following as reference when creating and editing docs: formatting inline code and code blocks.

Emphasize placeholders

Placeholders are a tricky topic in technical documentation and are one of the most common sources of confusion, especially for beginners. To strive for consistency, placeholders in the Prisma docs:

• are spelled in all-uppercase letters
• are prefixed and suffixed with two underscores
• use descriptive terms

As an example, consider the following code block where __DATABASE_CONNECTION_URL__ is a placeholder for the PostgreSQL connection URL:

datasource db {
  provider = "postgresql"
  url      = "__DATABASE_CONNECTION_STRING__"
}

Whenever you use a placeholder, explain how to obtain a value for the placeholder, or link to another resource that explains this. Explicitly call out that this is a placeholder that must be replaced with a "real value". Include an example of what that real value might look like:

datasource db {
  provider = "postgresql"
  url      = "postgresql://opnmyfngbknppm:XXX@ec2-46-137-91-216.eu-west-1.compute.amazonaws.com:5432/d50rgmkqi2ipus?schema=hello-prisma2"
}

Use Prettier code formatting

Install Prettier in VSCode. Prettier helps ensure your code examples and Markdown have consistent formatting, such as line spacing and indentation.

If you need to force Prettier to ignore a code block or section of Markdown, you can use // prettier-ignore:

<!-- prettier-ignore-start -->
function xyz() {
 console.log({a, b})
}
<!-- prettier-ignore-end -->

Use expressive variable names

Good:

const getUsers = (...)
const deleteUsers = (...)

Bad:

const results = (...) // Too generic
const foo = (...) // Too vague

Strive for code snippets to be valid

Ensure that code snippets you include are realistic examples that would work if run in the context presented.

Prisma schema naming conventions

When you create a Prisma schema for an example, follow the naming conventions we advise for users.

Lists of shell commands

When you need to provide a series of CLI commands as instructions to the reader, use a single block. Don't use a list unless you want to provide context for each step:

cd path/to/server
docker-compose up -d --build
./node_modules/.bin/sequelize db:migrate # or `npx sequelize db:migrate`
./node_modules/.bin/sequelize db:seed:all # or `npx sequelize db:seed:all`

Don't prepend CLI commands with $

Use terminal for CLI commands - this type of code block includes a $:

```terminal
npm install prisma
```

For example:

$npm install prisma

npm vs Yarn

Always use npm commands instead of yarn.

Error message reference

The error message reference is a semi-generated doc. Do not edit the list of error codes manually. Use the script to generate the error codes.

When you bring the error messages into the page, remove any double quotes around them.

Bad:

#### <inlinecode>P1008</inlinecode>

"Operations timed out after `{time}`"

Good:

#### <inlinecode>P1008</inlinecode>

Operations timed out after `{time}`

See also: Error message generation guide for Prisma technical writers