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:
- 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
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":
- a
.jpg
file - an
.xls
file - an
.env
file - For json files, see Special case: JSON
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, useJson
- 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 the highlight
property to highlight
Use the highlight
property if you need to highlight your code samples. For example:
```prisma highlight=3;normalgenerator 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 genericconst 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
ornpx sequelize db:migrate
./node_modules/.bin/sequelize db:seed:all
ornpx 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
- Navigate into the project directory:
cd path/to/server
- Start Docker containers:
docker-compose up -d --build
- Migrate your database schema:
./node_modules/.bin/sequelize db:migrate
ornpx sequelize db:migrate
- Seed the database:
./node_modules/.bin/sequelize db:seed:all
ornpx sequelize db:seed:all
Don't prepend CLI commands with $
Use terminal
for CLI commands - this type of code block includes a $
:
```terminalnpm 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