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 unless a question mark is required
  • Use <inlinecode>code</inlinecode> 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)

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 and type safe

  • "The code is type safe." (noun)
  • "This is type-safe code." (adjective)

Data source and datasource

  • The datasource block
  • "You must regenerate the 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".

Confusion can happen when you don’t use the Oxford comma.

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

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

Edit this page on GitHub