supabase/apps/docs/WORD_LIST.md

Supabase documentation word list

Use this list when you write or review Supabase documentation. It records preferred spelling, capitalization, and usage for terms that commonly appear in developer documentation.

This list supplements CONTRIBUTING.md. If the two documents conflict, follow CONTRIBUTING.md. Match literal code, API names, UI labels, and third-party product names even when they differ from this guidance, and format them as code or UI text as appropriate.

Many unambiguous rules in this list are checked by supa-mdx-lint. Run pnpm lint:mdx from apps/docs after editing MDX. A lint warning still requires judgment: rewrite the sentence instead of applying a replacement that changes its meaning.

Numbers and symbols

+

Don't use + to mean or later.

• Recommended: Postgres 15 or later
• Not recommended: Postgres 15+

&

Use and instead of & in prose, headings, navigation, and tables of contents. Keep & when it is part of a UI label, code, or a space-constrained table or diagram label.

A

abbreviations

Spell out an unfamiliar abbreviation on first use. Don't expand familiar technical abbreviations such as API, CPU, HTML, HTTP, or SQL unless the audience needs it.

Use for example instead of e.g. when practical. If space is constrained, write e.g. with both periods. Use that is instead of i.e..

The linter warns about malformed forms of e.g. and about i.e..

abort

Use stop, exit, cancel, or end in general prose. Use abort when it is the name of a command, signal, API, or operation.

above

Don't use above to refer to a location in a document or UI. Link to or name the section or control. For versions, use later.

access

When possible, use a more specific verb such as view, find, edit, open, or use. Keep access when it accurately describes authorization or connectivity.

admin

Use administrator in prose. Use admin when it is part of a product name, API, role, command, or UI label.

AI

You can use AI without spelling out artificial intelligence when the audience is familiar with the term.

allowlist and denylist

Use allowlist and denylist as nouns. Prefer a precise verb that describes the action instead of using either term as a verb.

• Recommended: Allow requests from the IP address.
• Recommended: Add the IP address to the allowlist.
• Not recommended: Allowlist the IP address.

Don't use blacklist or whitelist. The linter reports these terms as errors. When a literal code item contains one of them, format the item as code and explain what it does.

allows you to

Use lets you, or make the reader the subject of the sentence.

• Recommended: You can query the table.
• Recommended: The API lets you query the table.
• Not recommended: The API allows you to query the table.

alpha and beta

Use lowercase when describing a release stage. Preserve capitalization when it is part of an official product name.

among and between

Use between for distinct items, even when there are more than two. Use among for members of a group or items that aren't distinct.

and/or

Rewrite to use and, or, or explicitly state that either or both apply.

API

Use API for a web API or a language-specific API. Don't use API to mean an individual method, function, class, or endpoint.

app and application

Use app for web and mobile software intended for end users. Use application when it is part of an established term, such as application programming interface, or when the distinction is technically useful.

as and since

Use because when you mean causation. As and since can be mistaken for references to time.

authentication and authorization

Authentication verifies an identity. Authorization determines what an authenticated identity can access or do. Don't use the terms interchangeably.

Avoid authN and authZ in prose. Use authentication and authorization.

auto-

Follow the spelling established by the relevant technology. Common closed forms include autoscaling, autofill, and autogenerate. Don't invent a hyphenated variation when an established form exists.

B

backend

Write backend, not back-end or back end.

base64

Use base64 in general prose. Use the capitalization required by a formal name or literal code item.

below

Don't use below to refer to a location in a document or UI. Link to or name the section or control. For versions, use earlier.

black-box, gray-box, and white-box

Prefer a description of what the monitoring or testing method can observe. If the established term is necessary, define it on first use.

boolean

Use the spelling and capitalization of the programming-language type when referring to code. Use lowercase boolean for the abstract data type and uppercase Boolean for Boolean logic.

button

Use button only for an element that is actually a button. In desktop instructions, users click a button. Preserve the exact button label and format it in bold.

C

can, may, might, must, and should

• Use can for ability, permission, or an optional action.
• Use might for possibility or an uncertain outcome.
• Reserve may for policy or legal guidance when possible.
• Use must or need to for a requirement.
• Avoid ambiguous should. State whether an action is required, recommended, or optional.

checkboxes

Users select and clear checkboxes. Don't use check, uncheck, or deselect for these actions.

click

Use click for buttons, links, and other controls in a desktop interface. Don't write click on. Use tap when the environment is specifically a touch interface.

click here

Don't use click here or here as link text. Describe the destination or action.

client

In API documentation, a client is usually an app that sends requests. Don't use client as an abbreviation for client library when that could be ambiguous.

Use concurrent connections, not concurrent clients, when discussing database connections. The linter checks this usage.

codebase

Write codebase, not code base.

command-line interface

Name the specific interface, such as Supabase CLI. Use CLI after the name is clear.

config

Use configuration in general prose. Keep config when referring to a literal file, command, property, or established technical name.

console and dashboard

Use the product's official name. Don't use console and dashboard interchangeably, and don't call a UI a dashboard unless it presents a dashboard. Use Supabase Dashboard for the Supabase product.

currently

Avoid currently when the sentence describes the product's present behavior. State the behavior directly.

D

data

Treat data as a singular mass noun: the data is and less data.

data center

Write data center, not datacenter.

data source

Use data source in prose. Preserve datasource when it is a code item or official product term.

data type

Write data type, not datatype.

deprecate

Use deprecated when use is discouraged, usually because support will end. Don't use it to mean removed, deleted, or unavailable.

dialog

Use dialog for a UI element that presents information or asks for input. Don't use dialogue or popup.

directory and folder

Use directory in command-line contexts and folder in graphical interfaces. Match the product UI when it uses a specific term.

disable

Use disable or turn off for an available feature or option. Don't use disabled to mean that something is broken or unavailable.

display

Display is a transitive verb and requires an object.

• Recommended: The Dashboard displays the query results.
• Recommended: The query results appear.
• Not recommended: The query results display.

docs

Use documentation in prose. Use docs in informal contributor instructions, repository paths, URLs, or established product names.

dropdown

Prefer the specific control name, such as list or menu. Use dropdown only when the distinction matters, and don't use drop-down.

dummy

Don't use dummy for placeholders or sample values. Use placeholder, sample, or a name that describes the value's role. For the statistical concept commonly called a dummy variable, use indicator variable or another established, context-appropriate term.

E

easy, quick, and simple

Avoid claiming that a task is easy, quick, or simple. These words can be subjective and usually add no information. The linter warns about easy, easily, quickly, simple, and simply.

email

Write email, not e-mail. Don't use email as a verb; use send email.

enable

Use enable or turn on consistently for activating a feature. When describing capability, prefer lets you over enables you.

endpoint

Write endpoint, not end point. Don't use endpoint when the more specific term is function, method, or route.

enter

Use enter for adding text to a field. Use type only when the physical act of typing matters.

etc.

Avoid etc., and so on, and and more. Introduce a non-exhaustive list with including, such as, or for example.

execute

Use run when it has the same meaning. Keep execute when it is the precise technical term, such as an execute permission or query execution plan.

extract

Use extract instead of unarchive, uncompress, untar, or unzip in prose. Preserve literal command names.

F

fail over and failover

Use fail over as a verb. Use failover as a noun or adjective.

filename

Write filename, not file name.

file system

Write file system, not filesystem, unless the latter is part of a code item or official name.

fill in and fill out

Users fill in individual fields and fill out an entire form.

first person

Address the reader as you. Don't use singular first person (I, me, my, or mine); the linter reports it as an error.

Use we only when it clearly refers to Supabase, not when it means the writer and reader together.

foo, bar, and baz

Use meaningful placeholder names that help explain the example. Keep conventional placeholder names only when the convention itself is relevant.

frontend

Write frontend, not front-end or front end.

H

hardcode and hardcoded

Write hardcode and hardcoded without a hyphen.

health and healthy

When possible, state the observable condition, such as responding, available, or passing its health check. Don't use healthy when it could be ambiguous or anthropomorphic.

higher and lower

For version ranges, use later and earlier, not higher and lower.

hover

Use hold the pointer over when the reader must wait for the interface to react. Use point to when no waiting is required.

HTTPS

Write HTTPS, not HTTPs.

I

ID

Write ID, not Id or id, except when matching code. Use identifier when it is clearer.

impact

Use impact as a noun. Prefer affect as the verb.

• Recommended: The change affects performance.
• Not recommended: The change impacts performance.

index

Use indexes as the plural in database documentation. Use indices only in domains where it is the established term.

ingest

Use import, load, or copy for simple data movement. Use ingest when the operation also performs substantial processing.

in order to

Use to unless in order to is necessary to prevent ambiguity. The linter warns about in order to.

inline

Write inline, not in-line.

internet

Use lowercase internet except at the beginning of a sentence.

J

just

Remove just when it is filler. If it means only or previously, use the more specific word. The linter warns about just.

K

key

Don't use key to mean important. When referring to a technical key, identify the kind of key on first use.

key-value pair

Write key-value pair, not key/value pair or key value pair.

kill

Use stop, exit, cancel, or end in general prose. Preserve kill for literal commands, signals, and established technical operations.

L

later and earlier

Use later and earlier for version ranges.

• Recommended: Version 2.2 or later
• Not recommended: Version 2.2 or higher

latest, new, and soon

Avoid time-relative descriptions that become stale. Provide a version, date, or specific product state instead.

leverage

Use use or a more specific verb. The linter warns about leverage.

lifecycle

Write lifecycle, not life cycle or life-cycle.

login and log in

Use login as a noun or adjective and log in as a verb. Follow the terminology in the product UI when it uses sign in.

• Recommended: Open the login page, and then log in.
• Not recommended: Login to the Dashboard.

M

marketing language

Describe measurable behavior instead of making promotional claims. The linter warns about:

• best in class and best-in-class
• cutting edge and cutting-edge
• effortlessly
• game changer and game-changer
• hassle free and hassle-free
• powerful
• seamlessly

master and slave

Don't use master and slave together. Prefer terms that describe the relationship accurately, such as primary and replica, controller and worker, or publisher and subscriber.

When a literal code item uses either term, format it as code, explain it, and use the preferred term afterward.

media type

Use media type rather than MIME type. Use content type when referring to the Content-Type HTTP header or when it prevents ambiguity.

microservices

Write microservices, not micro-services.

might

Use might for possibility or an uncertain outcome.

must

Use must or need to for a requirement. Don't use must for a recommendation.

N

native

Use a more precise term when possible, such as built-in, platform-specific, or compiled. Don't use native to describe people.

numbers in product versions

Write an explicit comparison, such as version 3.0 or later. Don't use newer, older, higher, lower, or a trailing +.

O

OAuth 2.0

Write OAuth 2.0, not OAuth2, OAuth 2, or Oauth.

obviously and of course

Remove these phrases. They can sound dismissive and don't help the reader. The linter warns about both.

once

Use after if that is what you mean. Use once only to mean one time.

on-premises

Write on-premises, not on-premise, on premise, or on prem.

P

performant

Use a measurable or specific description, such as lower latency, uses less memory, or handles more concurrent connections.

persist

Avoid using persist as a transitive verb.

• Recommended: Store the session.
• Recommended: Make the session persistent.
• Not recommended: Persist the session.

plain text and plaintext

Use plain text in general contexts. Use plaintext in cryptography.

please

Don't use please in normal instructions. Use it only when asking permission, apologizing for an inconvenience, or requesting an action that primarily benefits Supabase. The linter warns about please.

plugin

Use plugin as a noun and plug in as a verb.

popup

Use the specific UI element, such as dialog, menu, or window. Don't use popup or pop-up as a generic noun.

Postgres

Use Postgres, not PostgreSQL, outside code and literal third-party names. The linter checks this usage.

powered by

Prefer with, by, or through, depending on the relationship. The linter warns about powered by.

prior to and subsequent to

Use before and after. The linter checks both phrases.

R

read-only

Always hyphenate read-only.

Realtime

Capitalize Realtime when referring to the Supabase product. Use lowercase real-time as an adjective with its ordinary meaning.

repository

Prefer repository in documentation prose. Repo is acceptable in informal contributor instructions and when space is constrained.

retry

Use retry as a verb or noun. Write around retriable, retryable, triable, and tryable when practical.

run time and runtime

Use runtime for an execution environment. Use run time for the time when a program runs or the duration of a run.

S

sanity check

Use preliminary check, confidence check, or a description of what the check validates.

screenshot

Use screenshot as a noun. Use take a screenshot, not screenshot as a verb. Redact secrets and personal information from screenshots.

select

Use select for choosing an item, selecting text, or marking a checkbox. Preserve the exact UI label in bold.

sensitive and confidential

Sensitive data is data whose disclosure might cause harm. Confidential data is protected against unauthorized access. Use the term that describes the relevant risk or control.

setup and set up

Use setup as a noun or adjective and set up as a verb.

• Recommended: Complete the setup to set up authentication.
• Not recommended: Setup authentication.

singular they

Use they, them, and their as gender-neutral singular pronouns. Don't use s/he, he/she, (s)he, or him/her. The linter reports these forms as errors.

slang abbreviations

Don't use internet slang in documentation. The linter warns about tl;dr, ymmv, rtfm, imo, and fwiw.

spin up

Use create or start unless you are literally describing a spinning disk.

SQL

Write a SQL query, not an SQL query. Use lowercase SQL keywords in code examples unless uppercase is required by the surrounding convention.

SSH

Don't use SSH or ssh as a verb.

• Recommended: Connect to the server by using SSH.
• Recommended: Use the ssh command.
• Not recommended: SSH into the server.

startup and start up

Use startup as a noun or adjective and start up as a verb.

Supabase

Capitalize Supabase outside code. Use Supabase Platform with both words capitalized. Match literal package names, commands, URLs, and code.

T

table name

Write table name as two words. Format a specific table name as code.

target

Avoid using target as a verb for people. Use intended for, designed for, or another description of the audience.

terminate

Use stop, exit, cancel, or end unless terminate has a specific technical meaning in the documented context.

third party and third-party

Use third party as a noun and third-party as an adjective. Don't abbreviate either form with 3rd.

this and that

Add a noun after this or that when the reference could be unclear.

• Recommended: This setting controls connection pooling.
• Not recommended: This controls connection pooling.

timeout and time out

Use timeout as a noun or adjective and time out as a verb.

timestamp

Write timestamp, not time stamp.

time zone and time-zone

Use time zone as a noun and time-zone as an adjective.

toggles

Users enable and disable features with toggles. Match and bold the visible label. Don't instruct the reader to click the toggle when the intended state can be stated directly.

U

UI

Use the specific interface or page name when possible. Use UI only when discussing a user interface as a general concept.

Match visible UI labels exactly and format them in bold. Describe the element with the correct noun when it improves clarity, such as the Connect button or the Database password field.

URL

Use URL, not web address, when writing for developers. Use descriptive link text rather than exposing a URL unless the URL itself is the subject.

user

Address the reader as you. Use user for a person who uses the software that the reader is building or administering.

utilize

Use use. Use utilization only when referring to the measured proportion of a resource in use. The linter warns about forms of utilize and utilise.

V

vague verbs

Describe the concrete action. The linter suggests:

• view and resolve errors instead of handle errors
• create, edit, or delete tables instead of manage tables
• query and update data instead of work with data

Choose a different precise verb if the suggested replacement doesn't match the actual operation.

versus

Write versus in prose, not vs. Use vs only when it is part of a literal name or when space is constrained.

W

web

Use lowercase web. Use the capitalization established by formal names such as WebAssembly.

we

Don't use we to mean the writer and reader together. Use you for the reader. We is acceptable when it unambiguously means Supabase.

while

Use while for events that occur at the same time. Use although or whereas for contrast. Use while, not whilst; the linter checks whilst.

will and would

Use present tense for current product behavior. Use will for an actual future event, not a predictable result. Replace would with can when describing capability.

workload

Use a more specific term, such as app, service, database, or job, when the meaning is known. If workload is the established technical term, define its scope on first use.

Y

you

Address the reader as you. Use user only for a person who uses the software that the reader is developing or administering.

Lint-enforced phrase groups

The alphabetical entries explain the intent behind the rules. This section mirrors the exact terminology checks configured in supa-mdx-lint/Rule004ExcludeWords. Update this section when those rules change.

Filler

The linter warns about actually, easily, easy, just, let's, obviously, of course, please, quickly, simple, simply, and that's it. Remove the term or state the intended meaning directly.

Marketing language

The linter warns about best in class, best-in-class, cutting edge, cutting-edge, effortlessly, game changer, game-changer, hassle free, hassle-free, powerful, and seamlessly. Describe specific behavior or measurable results instead.

Vague verbs

The linter suggests view and resolve errors for handle errors, create, edit, or delete tables for manage tables, and query and update data for work with data. Use a different precise replacement when the suggestion doesn't match the operation.

Apologies

The linter warns about oops and sorry. State what happened directly. Apologize only when an apology is genuinely useful to the reader.

First person

The linter reports I, I'm, me, my, and mine as errors. Address the reader as you and use an explicit noun for other actors.

Gender-neutral pronouns

The linter reports s/he, he/she, (s)he, and him/her as errors. Use the singular they or rewrite the sentence.

Inclusive language

The linter reports these terms as errors:

• mankind: use humankind or people
• manmade: use manufactured, artificial, or synthetic
• middleman: use intermediary
• blacklist: use denylist or a more precise term
• whitelist: use allowlist or a more precise term

Abbreviations

The linter corrects eg. and eg to e.g.. It replaces i.e., ie., and ie with that is. Prefer for example and that is in prose when space allows.

Powered by

The linter warns about powered by. Use with, by, or through, depending on the relationship.

Preferred usage

The linter suggests:

• Postgres for PostgreSQL
• concurrent connections for concurrent clients
• use for utilize and utilise
• uses for utilizes and utilises
• using for utilizing and utilising

Direct, concise language

The linter warns about these phrases:

• aforementioned: name the item
• amongst: use among
• endeavor or endeavour: use try
• facilitate: use help or describe the action
• for the purpose of: use to
• in order to: use to
• leverage: use use or a more precise verb
• prior to: use before
• subsequent to: use after
• whilst: use while

Internet slang

The linter warns about tl;dr, ymmv, rtfm, imo, and fwiw. Write out the meaning or remove the aside.

Attribution

Portions of this word list are modifications based on work created and shared by Google and used according to the terms of the Creative Commons Attribution 4.0 License. See the Google developer documentation style guide word list for the original work. Supabase-specific guidance and adaptations are maintained in this repository.