Prisma style guide

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

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.

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

Write concisely

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.

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.

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 comitted 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, i.e., 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 sparcely 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."

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…

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.

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

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"

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

TBD

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:

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 $

TBD

npm vs Yarn

Always use npm commands instead of yarn.

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.