Prisma style guide
Welcome! This guide contains information for writing and maintaining technical documentation for the Prisma tools. One major goal of this style guide is to ensure consistency in the Prisma documentation with respect to things like word choice, writing style, formatting and more.
This style guide is heavily inspired by the Gatsby Style Guide. Many sections have been bluntly copied, some others have been slightly edited and some are new and specific to the Prisma docs.
Word choice
Use "you" as the pronoun
Any content should use the second person ("you") to provide a conversational tone. This way, the text and instructions seem to speak directly to the person reading it. Try to avoid using the first person ("I", "we", "let's", and "us").
Using "you" in English is also more accurate than saying "we because typically only one person is reading the tutorial or guide at a time and the person who wrote the tutorial is not actually going through it with them, so "we" would be inaccurate. You might notice that some technical documentation uses third person pronouns and nouns like "they" and "the user", which add more distance and feel colder than the conversational and warm "you" and "your".
When to use "we"
You can use "we" when specifically referring to Prisma. For example:
"We recommend that you share a single instance of
PrismaClient
across your application.
Avoid words like "easy" and "just"
Avoid using words like "easy", "just" "simple" and "basic" because if users have a hard time completing the task that is supposedly "easy," they will question their abilities. 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 (referring to a completely different doc that someone may not have read)". Often, rephrasing results in stronger sentences that appeal to a wider range of contexts.
Use inclusive language
When you need to refer to one or more people in third-person, be sure to use inclusive, gender-neutral language if the gender of the person is not explicitly known. Use "they/them/their" instead of "he/him/his" or "she/her/her". Avoid words like "guys"
Avoid emojis, slang, and metaphors
Avoid using emojis or emotions in the docs and idiomatic expressions / slang, or metaphors. Prisma has a global community, and the cultural meaning of an emoji, emoticon, or slang may be different around the world. Use your best judgment! Also, emojis can render differently on different systems.
Avoid Latin terms
For example:
- et al
- etc
- i.e.
- e.g.
Avoid contractions
For example:
- You're (use "You are")
- It'll (use "It will")
Define jargon
Articles should be written with short, clear sentences, and use as little jargon as necessary.
Jargon: (n.) special words or expressions that are used by a particular profession or group and are difficult for others to understand: legal jargon.
All jargon should be defined immediately in plain English. In other words, pretend like your readers have basic coding experience but not necessarily experience with PWAs and the JAMstack (see what happened there? I just used two jargon words that need to be defined); you need to define words that newcomers might have a hard time understanding.
Referring to other parts of the docs
- Page
- Section
Technical word choice
Record
Refer to rows in the database as records. For example:
"The following create
query creates a single User
record."
Do not use:
- Entry
- Row
- Object
Model property
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
Writing style
Write concisely and avoid long blocks of text
Concise writing communicates the bare minimum without redundancy. Strive to make your writing as short as possible; this practice will often lead to more accurate and specific writing. To avoid large blocks of text:
- Use shorter paragraphs
- Use lists
- Use examples
- Use bold and emphasis
- Use tables
- Use diagrams
Use active voice
Use active voice instead of passive voice. Generally, it’s a more concise and straightforward way to communicate a subject. For example:
- (passive) The for loop in JavaScript is used by programmers to…
- (active) Programmers use the for loop in JavaScript to…
Be assertive
Use assertive language.
Good:
- Use the
createMany
method to create multiple records in a single transaction - You can use nested writes to create a user and that user's posts at the same time
Avoid:
- This example tries to..
- You might be able to..
- You could use..
Use clear hyperlinks
Hyperlinks should contain the clearest words to indicate where the link will lead you.
<!-- 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/)
Indicate when something is optional
When a paragraph or sentence offers an optional path, the beginning of the first sentence should indicate that it’s optional. For example, "if you’d like to learn more about xyz, see our reference guide" is clearer than "Go to the reference guide if you’d like to learn more about xyz."
This method allows people who would not like to learn more about xyz to stop reading the sentence as early as possible. This method also allows people who would like to learn more about xyz to recognize the opportunity to learn quicker instead of accidentally skipping over the paragraph.
Abbreviate terms
If you want to abbreviate a term in your article, write it out fully first, then put the abbreviation in parentheses. After that, you may use the abbreviation going for the rest of the article. For example, "In computer science, an abstract syntax tree (AST) is …".
Embrace redundancy
Meet the user where they are.
Grammar and formatting
Capitalize and spell out proper nouns
Although it can be tempting to use abbreviations like "Postgres" (instead of the official proper noun "PostgreSQL") or not worry about casing when writing "Javascript" (instead of "JavaScript"), we're committed to using the preferred notions 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)
- ...
If you're not sure about the spelling of a certain noun, the official homepage of it typically contains the proper spelling for you to look up.
Format titles and headers
Page titles and headings are sentence cased: only the initial word is uppercase. Neither of them need punctuation at the end of the phrase unless a question mark is required.
Use tables, bullet lists and numbered lists
Tables and lists are often the most concise way of presenting information. Use the elements whenever they feel appropriate. Here are few guidelines to help decide when to use which:
- Use bullet lists only when the order of the lists doesn't matter (e.g. an enumeration of the features of a database which don't have an inherent order)
- Use numbered lists only when the order of the list matters (e.g. when providing step-by-step instructions where one step builds on the previous)
- Use tables when you're enumerating 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)
Use italics and bold font
Italics and bold fonts can be a great way to emphasize certain parts of your sentence to the reader. Use bold font more sparsely and only when you want this part 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.
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
."
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" e.g. an Italian painter, sculptor, and architect. It makes things clearer.
Prefer US English
For words that have multiple spellings, prefer the US English word over British or Canadian English. For example:
- "color" over "colour"
- "behavior" over "behaviour"
Writing code snippets
Introduce all code snippets
Write a short introductory sentence that:
- Explains what the code snippet is doing
- Links to reference documentation if applicable
For example:
The following [`createMany`](..) query creates several new `User` records:
The following [`createMany`](..) query:Creates several `User` recordsCreates several nested `Post` recordsCreates 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 = ["orderByRelation"]}```
Use inline code only when referring to "code concepts"
TBD
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
- prefixed and suffixed with two underscores
- using 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're using a placeholder, you should make sure that you directly explain or at least link out to another resource that explains how to obtain a value for the placeholder. You should also explicitly call out that this is a placeholder that needs to get replaced with a "real value" including 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
TBD
Use expressive variable names
Good:
const getUsers = (...)const deleteUsers = (...)
Bad:
const results = (...) // Too genericconst foo = (...) // Too vague
Strive for code snippets to be "valid"
TBD
Avoid too many inline comments
TBD
Lists of shell commands
When you need to provide a series of CLI commands as instructions to the reader, don't use a list unless you're providing 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/serverdocker-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
.
Spelling
Hyphens
Hyphens are used according to these rules.
Sometimes there are some terms where it's not clear whether to use a hyphen or not. In order to strive for consistency, we list those terms here as a rule for using them throughout the Prisma documentation.
Spell without hyphen
- Use case
- Command line
- Auto format
- Type safety
Spell with hyphen
- Compile-time
Spell as one word
- Autocomplete
Type-safe and type safe
- "The code is type safe."
- "This is type-safe code."
Data source and datasource
- The
datasource
block - "You must regenerate the client when you introduce a new data source"
Boilerplate
The following section contains frequently used phrases or blocks of content that you can re-use:
Introducing a preview feature
To enable this feature, add `orderByRelation` to `previewFeatures` in your schema:```prisma highlight=3;normalgenerator client {provider = "prisma-client-js"previewFeatures = ["orderByRelation"]}
Making recommendations
If it is a Prisma recommendation, use:
"We recommend that you share a single instance of
PrismaClient
across your application."
If it is an industry standard, use:
"It is recommended practice to limit he number of database connections to X."