apps/docs/WORD_LIST.md
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.
+Don't use + to mean or later.
&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.
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..
Use stop, exit, cancel, or end in general prose. Use abort when it is the
name of a command, signal, API, or operation.
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.
When possible, use a more specific verb such as view, find, edit, open, or use. Keep access when it accurately describes authorization or connectivity.
Use administrator in prose. Use admin when it is part of a product name, API, role, command, or UI label.
You can use AI without spelling out artificial intelligence when the audience is familiar with the term.
Use allowlist and denylist as nouns. Prefer a precise verb that describes the action instead of using either term as a verb.
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.
Use lets you, or make the reader the subject of the sentence.
Use lowercase when describing a release stage. Preserve capitalization when it is part of an official product name.
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.
Rewrite to use and, or, or explicitly state that either or both apply.
Use API for a web API or a language-specific API. Don't use API to mean an individual method, function, class, or endpoint.
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.
Use because when you mean causation. As and since can be mistaken for references to time.
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.
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.
Write backend, not back-end or back end.
Use base64 in general prose. Use the capitalization required by a formal name or literal code item.
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.
Prefer a description of what the monitoring or testing method can observe. If the established term is necessary, define it on first use.
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.
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.
Users select and clear checkboxes. Don't use check, uncheck, or deselect for these actions.
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.
Don't use click here or here as link text. Describe the destination or action.
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.
Write codebase, not code base.
Name the specific interface, such as Supabase CLI. Use CLI after the name is clear.
Use configuration in general prose. Keep config when referring to a literal file, command, property, or established technical name.
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.
Avoid currently when the sentence describes the product's present behavior. State the behavior directly.
Treat data as a singular mass noun: the data is and less data.
Write data center, not datacenter.
Use data source in prose. Preserve datasource when it is a code item or
official product term.
Write data type, not datatype.
Use deprecated when use is discouraged, usually because support will end. Don't use it to mean removed, deleted, or unavailable.
Use dialog for a UI element that presents information or asks for input. Don't use dialogue or popup.
Use directory in command-line contexts and folder in graphical interfaces. Match the product UI when it uses a specific term.
Use disable or turn off for an available feature or option. Don't use disabled to mean that something is broken or unavailable.
Display is a transitive verb and requires an object.
Use documentation in prose. Use docs in informal contributor instructions, repository paths, URLs, or established product names.
Prefer the specific control name, such as list or menu. Use dropdown only when the distinction matters, and don't use drop-down.
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.
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.
Write email, not e-mail. Don't use email as a verb; use send email.
Use enable or turn on consistently for activating a feature. When describing capability, prefer lets you over enables you.
Write endpoint, not end point. Don't use endpoint when the more specific term is function, method, or route.
Use enter for adding text to a field. Use type only when the physical act of typing matters.
Avoid etc., and so on, and and more. Introduce a non-exhaustive list with including, such as, or for example.
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.
Use extract instead of unarchive, uncompress, untar, or unzip in prose. Preserve literal command names.
Use fail over as a verb. Use failover as a noun or adjective.
Write filename, not file name.
Write file system, not filesystem, unless the latter is part of a code item or official name.
Users fill in individual fields and fill out an entire form.
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.
Use meaningful placeholder names that help explain the example. Keep conventional placeholder names only when the convention itself is relevant.
Write frontend, not front-end or front end.
Write hardcode and hardcoded without a hyphen.
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.
For version ranges, use later and earlier, not higher and lower.
Use hold the pointer over when the reader must wait for the interface to react. Use point to when no waiting is required.
Write HTTPS, not HTTPs.
Write ID, not Id or id, except when matching code. Use identifier when it is clearer.
Use impact as a noun. Prefer affect as the verb.
Use indexes as the plural in database documentation. Use indices only in domains where it is the established term.
Use import, load, or copy for simple data movement. Use ingest when the operation also performs substantial processing.
Use to unless in order to is necessary to prevent ambiguity. The linter warns about in order to.
Write inline, not in-line.
Use lowercase internet except at the beginning of a sentence.
Remove just when it is filler. If it means only or previously, use the more specific word. The linter warns about just.
Don't use key to mean important. When referring to a technical key, identify the kind of key on first use.
Write key-value pair, not key/value pair or key value pair.
Use stop, exit, cancel, or end in general prose. Preserve kill for literal commands, signals, and established technical operations.
Use later and earlier for version ranges.
Avoid time-relative descriptions that become stale. Provide a version, date, or specific product state instead.
Use use or a more specific verb. The linter warns about leverage.
Write lifecycle, not life cycle or life-cycle.
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.
Describe measurable behavior instead of making promotional claims. The linter warns about:
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.
Use media type rather than MIME type. Use content type when referring to the
Content-Type HTTP header or when it prevents ambiguity.
Write microservices, not micro-services.
Use might for possibility or an uncertain outcome.
Use must or need to for a requirement. Don't use must for a recommendation.
Use a more precise term when possible, such as built-in, platform-specific, or compiled. Don't use native to describe people.
Write an explicit comparison, such as version 3.0 or later. Don't use newer,
older, higher, lower, or a trailing +.
Write OAuth 2.0, not OAuth2, OAuth 2, or Oauth.
Remove these phrases. They can sound dismissive and don't help the reader. The linter warns about both.
Use after if that is what you mean. Use once only to mean one time.
Write on-premises, not on-premise, on premise, or on prem.
Use a measurable or specific description, such as lower latency, uses less memory, or handles more concurrent connections.
Avoid using persist as a transitive verb.
Use plain text in general contexts. Use plaintext in cryptography.
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.
Use plugin as a noun and plug in as a verb.
Use the specific UI element, such as dialog, menu, or window. Don't use popup or pop-up as a generic noun.
Use Postgres, not PostgreSQL, outside code and literal third-party names. The linter checks this usage.
Prefer with, by, or through, depending on the relationship. The linter warns about powered by.
Use before and after. The linter checks both phrases.
Always hyphenate read-only.
Capitalize Realtime when referring to the Supabase product. Use lowercase real-time as an adjective with its ordinary meaning.
Prefer repository in documentation prose. Repo is acceptable in informal contributor instructions and when space is constrained.
Use retry as a verb or noun. Write around retriable, retryable, triable, and tryable when practical.
Use runtime for an execution environment. Use run time for the time when a program runs or the duration of a run.
Use preliminary check, confidence check, or a description of what the check validates.
Use screenshot as a noun. Use take a screenshot, not screenshot as a verb. Redact secrets and personal information from screenshots.
Use select for choosing an item, selecting text, or marking a checkbox. Preserve the exact UI label in bold.
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.
Use setup as a noun or adjective and set up as a verb.
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.
Don't use internet slang in documentation. The linter warns about tl;dr, ymmv, rtfm, imo, and fwiw.
Use create or start unless you are literally describing a spinning disk.
Write a SQL query, not an SQL query. Use lowercase SQL keywords in code examples unless uppercase is required by the surrounding convention.
Don't use SSH or ssh as a verb.
ssh command.Use startup as a noun or adjective and start up as a verb.
Capitalize Supabase outside code. Use Supabase Platform with both words capitalized. Match literal package names, commands, URLs, and code.
Write table name as two words. Format a specific table name as code.
Avoid using target as a verb for people. Use intended for, designed for, or another description of the audience.
Use stop, exit, cancel, or end unless terminate has a specific technical meaning in the documented context.
Use third party as a noun and third-party as an adjective. Don't abbreviate
either form with 3rd.
Add a noun after this or that when the reference could be unclear.
Use timeout as a noun or adjective and time out as a verb.
Write timestamp, not time stamp.
Use time zone as a noun and time-zone as an adjective.
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.
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.
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.
Address the reader as you. Use user for a person who uses the software that the reader is building or administering.
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.
Describe the concrete action. The linter suggests:
Choose a different precise verb if the suggested replacement doesn't match the actual operation.
Write versus in prose, not vs. Use vs only when it is part of a literal name
or when space is constrained.
Use lowercase web. Use the capitalization established by formal names such as WebAssembly.
Don't use we to mean the writer and reader together. Use you for the reader. We is acceptable when it unambiguously means Supabase.
Use while for events that occur at the same time. Use although or whereas for contrast. Use while, not whilst; the linter checks whilst.
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.
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.
Address the reader as you. Use user only for a person who uses the software that the reader is developing or administering.
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.
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.
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.
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.
The linter warns about oops and sorry. State what happened directly. Apologize only when an apology is genuinely useful to the reader.
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.
The linter reports s/he, he/she, (s)he, and him/her as errors. Use the singular they or rewrite the sentence.
The linter reports these terms as errors:
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.
The linter warns about powered by. Use with, by, or through, depending on the relationship.
The linter suggests:
The linter warns about these phrases:
The linter warns about tl;dr, ymmv, rtfm, imo, and fwiw. Write out the meaning or remove the aside.
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.