Skip to main content

Spelling, punctuation, and formatting

Avoid contractions​

In keeping with our conversational style, some contractions are OK:

  • Contractions that include the words "is" or "are". For example: it's and you're.
  • However, use contractions sparingly.

However, avoid other contractions. For example:

  • It'll (use "It will")

Text emphasis​

Use text emphasis (bold, and italic) sparingly. In keeping with the calm tone of our docs, and to help readability, avoid a sea of emphasized and formatted text.

Italic and bold text can be a great way to emphasize certain parts of your sentence to the reader. Use bold text more sparingly, and only when you want some text to stand out from the entire paragraph (so that it's visible when a reader only "scans" the page instead of properly reading it). Use italics for words that introduce new concepts for the first time.

Do not use ALL CAPS to emphasize text.

If you are in doubt about whether to emphasize some text, then don't do it.

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 code for code in headings - this is required by our navigation elements

Tables, bullet lists, and numbered lists​

Tables and lists are often the most concise way to present information. Use these elements whenever they feel appropriate. Here are a few guidelines:

  • Use a bullet list when the order of the list doesn't matter (e.g. an enumeration of the features of a database which don't have an inherent order).
  • Use a numbered list only when the order of the list matters (e.g. when providing step-by-step instructions where one step builds on the previous).
  • Use a table to describe things that share a number of similar properties/characteristics (e.g. the parameters for an API call which all have a "name", a "type", are required or optional and need a description).
  • For both numbered/ordered lists and bullet lists, add a period on the end if it is a complete sentence. This is most common in ordered lists, with a series of steps.

Hyphens​

Use hyphens according to these rules.

Sometimes there are some terms where it's not clear whether to use a hyphen or not. To strive for consistency, we list those terms here.

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"

Files and file types​

When you refer to a file or file type, use lower case and code format, and include the dot. Use "an" as the preposition if the filename extension, when pronounced, starts with a vowel, otherwise use "a":

Note: when you refer to a specific file, use the capitalization that is used in the file name:

  • the schema.prisma file

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

Use inline code format when referring to strings in text​

For example:

"The following query returns all records where the email field is equal to Sarah."

Avoid excessive code formatting​

Documents can quickly get visually cluttered if they have too much special formatting. Our docs are highly technical, and we often refer to code snippets or technical keywords that appear in the user's code. For these keywords, it's appropriate for us to use code formatting. However, we should not refer to general technologies (such as JSON) with code formatting:

For example:

Prisma automatically converts JavaScript objects (for example, { extendedPetsData: "none"}) to JSON.

Make lists clear with the Oxford Comma​

Use the Oxford Comma except in titles. It is a comma used after the penultimate item in a list of three or more items, before "and" or "or". It makes things clearer. Example: "... an Italian painter, sculptor, and architect".

In rare cases, the Oxford Comma can make a list less clear. In this situation, re-order the list where possible to make the meaning clear.

Code snippets​

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 highlight comments to highlight code​

If you need to highlight lines in your code samples, use the highlight magic comments. For example:

```prisma
generator client {
  provider        = "prisma-client-js"
  //highlight-next-line
  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 expressive variable names​

Good:

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

Bad:

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

Include valid code snippets​

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

Follow Prisma Schema naming conventions​

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

List shell commands in a single code block​

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:

Bad​

  • 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

Better​

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`

or

  1. Navigate into the project directory: cd path/to/server
  2. Start Docker containers: docker compose up -d --build
  3. Migrate your database schema: ./node_modules/.bin/sequelize db:migrate or npx sequelize db:migrate
  4. Seed the database: ./node_modules/.bin/sequelize db:seed:all or npx sequelize db:seed:all

Don't prepend CLI commands in code blocks with $​

Use the terminal language meta string for CLI commands - this type of code block includes a $:

```terminal
npm install prisma
```

For example:

npm install prisma

Use npm as the default package manager​

All examples should use npm. Other package manager options (yarn, pnpm, bun) should only be used if commands differ and never as the default.