The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs: add a standalone style guide (#50742)
Miranda Limonczenko8fa75be01b81
diff --git a/apps/docs/WORD_LIST.md b/apps/docs/WORD_LIST.mdindex 38b2bc1b4ad..4b4fa46fe1b 100644--- a/apps/docs/WORD_LIST.md+++ b/apps/docs/WORD_LIST.md@@ -1,955 +1,3 @@# 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](./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.--The `/write-the-docs` and `/edit-the-docs` agent skills apply this list as you draft.--Every rule here 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.`.--### 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_.-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.--### 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. Don't use _easy_, _easily_, _quickly_,-_simple_, or _simply_.---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_).--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.--### 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.--## 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 instead of _leverage_.--### lifecycle--Write _lifecycle_, not _life cycle_ or _life-cycle_.--### login and log in--Don't use _login_ or _log in_ in prose. Use _sign in_. See-[sign in and sign-in](#sign-in-and-sign-in).--## M--### marketing language--Describe measurable behavior instead of making promotional claims. Don't use:--- _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--Spell out zero through nine. Use numerals for 10 and greater. Use numerals-regardless for versions, technical quantities, step and page numbers, prices, and-percentages, and throughout a sentence that mixes a number under 10 with a larger-one.--- **Recommended**: four options, 24 hours, version 3, 128 bits, step 2, 40%-- **Not recommended**: 4 options, twenty-four hours--Spell out ordinals. Group digits in large numbers with commas, counting left from-the decimal point. Write fractions as decimals where practical. Use a hyphen with-no spaces for a range.--- **Recommended**: first, forty-third, 1,532,784 bytes, 0.75, 2012-2016-- **Not recommended**: 1st, 1532784 bytes, three-quarters, 2012 - 2016--Omit a count of steps or items unless the count helps the reader plan. Name the-action or link the heading rather than citing a step or section number.--- **Recommended**: To connect to your database:-- **Recommended**: After you create the project, copy the project URL.--### 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.--### 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.--### 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.--### powered by--Don't use _powered by_. Prefer _with_, _by_, or _through_, depending on the-relationship.--### prior to and subsequent to--Use _before_ and _after_.--## 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.--### sign in and sign-in--Use _sign in_, _sign out_, and _sign up_ as verbs. Use the hyphenated forms-_sign-in_, _sign-out_, and _sign-up_ as nouns or adjectives. Match the product UI-labels **Sign in**, **Sign out**, and **Sign up**.--Keep _login_, _log in_, _logout_, _log out_, and `logOut` when quoting-third-party UI or when they are part of code, routes, URL slugs, CLI commands, or-established feature names such as _social login_.--### singular they--Use _they_, _them_, and _their_ as gender-neutral singular pronouns. Don't use-_s/he_, _he/she_, _(s)he_, or _him/her_.--### slang abbreviations--Don't use internet slang in documentation, such as _tl;dr_, _ymmv_, _rtfm_, _imo_,-or _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_, not _utilize_ or _utilise_. Use _utilization_ only when referring to the-measured proportion of a resource in use.--## V--### vague verbs--Describe the concrete action:--- _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.--### vCPU--Use _vCPU_ (plural _vCPUs_) for the CPU resources of Supabase compute sizes.-Don't describe Supabase compute in _cores_.--_Core_ remains correct for hardware the reader owns or manages, such as-self-hosting requirements or a migration VM, and in general CPU discussion.--- Recommended: The 16XL compute size has 64 vCPUs.-- Recommended: Run the migration from a VM with 8 CPU cores.-- Not recommended: The 16XL compute size has 64 cores.--### 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_.--### 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.--## Phrase groups--The alphabetical entries explain the intent behind each rule. This section collects-the full term lists in one place, grouped by the problem they cause.--### Filler--Don't use _actually_, _easily_, _easy_, _just_, _let's_, _obviously_,-_of course_, _please_, _quickly_, _simple_, _simply_, or _that's it_. Remove the term or state the intended meaning directly.-_please_ is the exception: keep it when asking permission, apologizing for an-inconvenience, or requesting an action that primarily benefits Supabase.--### Marketing language--Don't use _best in class_, _best-in-class_, _cutting edge_,-_cutting-edge_, _effortlessly_, _game changer_, _game-changer_, _hassle free_,-_hassle-free_, _powerful_, or _seamlessly_. Describe specific behavior or-measurable results instead.--### Vague verbs--Use _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 none of these match the operation.--### Apologies--Don't use _oops_ or _sorry_. State what happened directly. Apologize-only when an apology is genuinely useful to the reader.--### First person--Don't use _I_, _I'm_, _me_, _my_, or _mine_. Address the-reader as _you_ and use an explicit noun for other actors.--### Gender-neutral pronouns--Don't use _s/he_, _he/she_, _(s)he_, or _him/her_. Use the-singular _they_ or rewrite the sentence.--### Inclusive language--Don't use these terms:--- _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--Write _e.g._ with both periods, not _eg._ or _eg_. Replace _i.e._, _ie._, and-_ie_ with _that is_. Prefer _for example_ and _that is_ in prose when space-allows.--### Powered by--Don't use _powered by_. Use _with_, _by_, or _through_, depending on the-relationship.--### Preferred usage--Use:--- _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--Don't use 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--Don't use _tl;dr_, _ymmv_, _rtfm_, _imo_, or _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](https://creativecommons.org/licenses/by/4.0/).-See the-[Google developer documentation style guide word list](https://developers.google.com/style/word-list)-for the original work. Supabase-specific guidance and adaptations are maintained-in this repository.+This file moved to [`style-guide/WORD_LIST.md`](./style-guide/WORD_LIST.md).diff --git a/apps/docs/style-guide/01-voice-and-tone.md b/apps/docs/style-guide/01-voice-and-tone.mdnew file mode 100644index 00000000000..2c9ccfebf2f--- /dev/null+++ b/apps/docs/style-guide/01-voice-and-tone.md@@ -0,0 +1,241 @@+# Voice and tone++Our voice and tone are clean and straightforward. Elegant prose is succinct: it brings a+reader to understanding without spending extra words.++Apply this document to every sentence you write, whether you're drafting a page or+changing one line on an existing one.++It covers the sentence level. For how a page divides into sections, see+[`03-page-structure.md`](./03-page-structure.md). For which component renders a piece of+information, see [`02-elements.md`](./02-elements.md).++| If you're deciding | Read |+| ---------------------------------------- | ----------------------------------------------- |+| How to mentally frame how you write | [Audience](#audience) |+| How to write sharper and more succinctly | [Brevity](#brevity) |+| How to write consistently and correctly | [Sentence construction](#sentence-construction) |++## Audience++### Write for the reader++The reader is a developer with a job to do, arriving mid-task from a search result+rather than from the top of the page. Their Postgres experience ranges from none to+deep, and they may be evaluating Supabase or already running it in production. Think+about the task they came to complete. Tell them what, and only what, they need to know+to finish it.++### Write for a massive global audience++Many readers have a native language that isn't English. Conversational, direct English+is easier to understand, localize, and read aloud.++### Write for a human and an LLM at once++Both read our pages. Some principles overlap while others don't. For a human, be kind+and respect their free will. For an LLM, you may need to nudge it to choose the best+practice. Use clean procedures and lots of code examples to make the best path the+easiest choice.++### Write like you talk++Many readers who use English as an additional language learn conversational rather than+academic English. Use words and sentences that sound natural when spoken. Read your+writing out loud to find the clearest phrasing.++### Avoid idioms and colloquialisms++A phrase like `piece of cake` is often specific to a region or culture.++### Don't use ableist language++Words that use disability as a metaphor for something bad exclude the readers they+describe.++### Address the reader as `you`++Don't use `we` to refer to the reader. Use `we` only to refer to the Supabase team.++## Brevity++### Prefer short, direct sentences++Express one relationship at a time and avoid unnecessary compound structures. Each+sentence gets easier to understand, localize, and interpret consistently.++Aim for fewer than 26 words per sentence. Past that, a reader has to hold too much at+once, and a listener using a screen reader has no way to scan back.++### Omit needless words++Cut every word that does no work. The replacements below recur often enough to be worth+memorizing.++| Wordy | Direct |+| ------------------------------ | -------- |+| the question as to whether | whether |+| is able to, has the ability to | can |+| in the event that | if |+| at this point in time | now |+| make a decision about | decide |+| provides support for | supports |++### Cut repeated points++If you can remove a sentence without losing information, remove it. Watch for a section+that restates what an earlier section established, and for three phrasings of one idea:+`It's free`, `You won't be billed`, `No charge`.++### Use the positive form++State what something does. A positive sentence is shorter and tells the reader what to+do next. Double negatives and nested exceptions are the hardest version of this to read.++- **Recommended**: `You can continue without a path.`+- **Not recommended**: `A missing path won't prevent you from continuing.`++- **Recommended**: `Use an admonition when a reader might otherwise miss information that affects their outcome.`+- **Not recommended**: `Don't use an admonition unless a reader might otherwise miss information that affects their outcome.`++### Cut mannered prose++Some sentences exist to sound composed. They carry nothing, and these three are the+common shapes:++- **Antithesis.** `X, not Y`, where Y is the negation of X. The negative half feels+ balanced and adds no information, and the sentence after it usually explains the point+ properly anyway. Delete the half after the comma and check whether anything was lost.+- **Rhythm for its own sake.** Three examples where two would do, or a clause added to+ balance a sentence.+- **The aphoristic closer.** A final sentence that restates the paragraph in a+ tidier shape. The paragraph already said it.++Contrast is worth keeping when both halves are real and the reader needs the comparison.+A recommended and not-recommended pair qualifies, as does a concrete substitution like+`select` rather than `SELECT`.++- **Recommended**: `Write alt text that describes the image. A topic name is what the nearby heading already says.`+- **Not recommended**: `Write alt text that describes the image, not the topic.`++### Be specific and concrete++A vague verb makes the reader guess at the operation. Name the operation instead.++- **Recommended**: `Create, edit, and delete tables in the Table Editor.`+- **Not recommended**: `Manage your tables in the Table Editor.`++[`WORD_LIST.md`](./WORD_LIST.md) lists the vague verbs that come up most often. The+principle extends past that list: if a verb could describe five different operations,+it's the wrong verb.++### Keep coordinate ideas parallel++List items and procedure steps are coordinate ideas, so give them the same grammatical+form. A step list that mixes imperatives with descriptions reads as though the steps do+different kinds of work.++- **Recommended**: `Install the CLI`, `Start the local stack`, `Apply the migration`+- **Not recommended**: `Install the CLI`, `The local stack starts next`, `Applying the migration`++### Put the emphatic words at the end of the sentence++The end of a sentence is where a reader's attention lands, so put the consequence there+rather than in the middle.++- **Recommended**: `A table with Row Level Security enabled and no policy returns no rows to every client.`+- **Not recommended**: `Every client gets no rows back from a table that has Row Level Security enabled and no policy, which is worth knowing.`++## Sentence construction++### Cover one topic in each paragraph++Start a new paragraph when the topic changes, or when you move between [information+types](./03-page-structure.md). Short paragraphs are fine.++Break up a dense paragraph rather than leaving it whole. A wall of text is hard to scan.+It is harder still for a reader who is listening to it, or who has trouble keeping their+place. When one paragraph carries several points, split it, or turn the points into a+list.++### Use complete sentences by default++They identify the actor and the action, which reduces ambiguity for readers,+translators, and agents. Use sentence fragments only where they improve scanning, such+as headings, labels, or short list items.++### Don't rely on a heading to carry meaning++Headings guide the reader's eye and organize the page, but the content beneath one has+to stand on its own. The first sentence can restate the heading, even if that sounds+redundant. Readers skim headings and then return to the section that interests them, so+the opening sentence is what confirms they're in the right place.++### Keep important information out of parentheses++Some readers skip anything parenthesized, so a step they need can't live there.++Reach for parentheses when the content is brief and genuinely supplementary:++- Introducing an acronym after spelling it out: `full-text search (FTS)`+- Marking an item `(Optional)`+- A short example inside a step: ``Enter a six-digit hex number (for example, `228B22`), and then select **OK**.``++Rewrite as a separate sentence when the aside grows past a few words, or when it carries+something the reader has to act on:++- **Recommended**: ``Enter a six-digit hex number, and then select **OK**. For example, for forest green, enter `228B22`.``+- **Not recommended**: ``Enter a six-digit hex number (for example, if you want the color forest green, enter `228B22`), and then select **OK**.``++Don't use parentheses for optional plurals. Write `one or more tables`, not `table(s)`.+Parentheses required by Markdown links or code syntax aren't prose parentheticals.++### Don't bound an aside with dashes where a direct sentence reads better++A pair of dashes interrupts the sentence the same way parentheses do, and the+interruption is usually a second sentence trying to escape. Google allows a dash in+place of parentheses; Supabase docs prefer the separate sentence.++- **Recommended**: `Don't add steps to reach a minimum. The range organizes information; it isn't a required length.`+- **Not recommended**: `Don't add steps to reach a minimum — the range organizes information, it isn't a required length.`++### Put the condition before the instruction++When an action only applies in some cases, name the case first. A reader who sees the+condition up front can skip the whole sentence. A reader who meets it at the end has+already read the instruction for nothing.++- **Recommended**: `To delete the entire document, click **Delete**.`+- **Not recommended**: `Click **Delete** if you want to delete the entire document.`+- **Recommended**: `For more information, see [Row Level Security](/docs/guides/database/postgres/row-level-security).`+- **Not recommended**: `See [Row Level Security](/docs/guides/database/postgres/row-level-security) for more information.`++The same order applies to a procedure step that branches. Put the `if` first, so a+reader can pass over a step that isn't theirs.++### Don't refer to the position of something on the page++`Above`, `below`, and `the right-hand side` assume a reader who sees the page laid out+the way you do. Position also changes with screen size and breaks when content moves.++- **Recommended**: `In the preceding diagram, the client calls the pooler.`+- **Not recommended**: `In the diagram above, the client calls the pooler.`++#### Spell out an abbreviation on first use++The exception is an abbreviation as familiar as `API` or `SQL`. Write full-text search+(FTS) once, then use `FTS`. A screen reader may read an unfamiliar abbreviation as a+word.++### Use the Oxford comma++Write `functions, tables, and indexes`.++### Use American English++Write `color, organize, center, and artifact`.++### Use the present tense++Write `the AI assistant answers your question` rather than `the AI assistant will answer+your question`.diff --git a/apps/docs/style-guide/02-elements.md b/apps/docs/style-guide/02-elements.mdnew file mode 100644index 00000000000..ea9085ba8f5--- /dev/null+++ b/apps/docs/style-guide/02-elements.md@@ -0,0 +1,463 @@+# Choose your components++Once you know what kind of information you have, this is the catalog of forms it can+take. Each entry leads with when the component is warranted, then its syntax.++"Component" means the MDX components the docs app provides, such as `<Admonition>` and+`<Tabs>`. "Element" means a plain Markdown construct, such as a list or a heading.++| If you're deciding | Read |+| -------------------------------------------------------- | --------------------------------------------- |+| Which form the information should take | [Choosing a component](#choosing-a-component) |+| How to handle admonitions, emphasis, headings, and lists | [Text](#text) |+| How to write steps, code, and tabs | [Steps and code](#steps-and-code) |+| How to show structured data or a diagram | [Data and diagrams](#data-and-diagrams) |+| How to add an image or a video | [Media](#media) |+| How to link out or list related pages | [Navigation](#navigation) |+| Which constructs to leave out | [Don't use these](#dont-use-these) |++## Choosing a component++Start from the information type, per [`03-page-structure.md`](./03-page-structure.md).++| You have | Reach for |+| ------------------------------------------------- | -------------------------------------------------- |+| Actions the reader performs in order | A [procedure](#procedures) |+| A stage-by-stage explanation | Prose, or a when/then [table](#tables) |+| The parts of something | A [table](#tables) or a [diagram](#diagrams) |+| A warning or a rule the reader must not miss | An [admonition](#admonitions) |+| A definition or an idea | Prose, a [list](#lists), or a [diagram](#diagrams) |+| Alternative instructions per platform or language | [Tabs](#tabs) |+| A curated set of links on an index page | A [content listing](#content-listings) |++When a phrase fits more than one category, pick the most specific one.++## Text++### Admonitions++#### Use an admonition for information a reader might otherwise miss++Reach for one when missing the information would change the outcome of the task. Use+one to separate helpful but optional guidance from the main flow. Don't+use one for information that belongs in the main explanation or procedure. They+highlight important information and get less effective when overused, so don't stack+them or use them as decoration.++#### Begin every admonition with its impact and purpose: the "so what."++Use the first sentence to tell the reader why the information matters: what could+happen, what changes, or what benefit they gain. Add background or instructions after+the impact is clear.++- **Recommended**: `Deleting this project permanently removes its database and backups. Export any data that you want to keep before you continue.`+- **Not recommended**: `Before you continue, there are a few things that you should know about project deletion.`++#### Don't restate an admonition in the body text++An admonition and the paragraph next to it should cover distinct points. A risk stated+twice reads as an editing mistake and trains readers to skip the box.++Choose the `type` that matches the severity:++| Type | Use for |+| ------------- | ------------------------------------------------------------------- |+| `danger` | Data loss, exposed data, or another severe, hard-to-reverse outcome |+| `deprecation` | A deprecated feature or behavior |+| `caution` | Bugs, failed operations, or unexpected results, short of `danger` |+| `note` | A prerequisite, constraint, or clarification that carries no risk |++For `danger` and `caution`, state the consequence first, then how to avoid it. For+`deprecation`, state how the change affects the reader, then the migration path. When a+note is essential to completing a step, put it in the procedure instead of an+admonition.++Structure an admonition with these props:++- `title` (optional): a short callout title. Don't put Markdown or HTML headings+ inside an admonition. If the content needs a heading to structure the page, move the+ heading and its section outside the admonition.+- `children`: rich body content such as paragraphs, lists, links, and code.+- `actions` (optional): standalone calls to action, kept separate from the body.+ Contextual links and interactive examples stay in the body when they're part of the+ explanation.++```mdx+<Admonition type="note" title="Optional title" actions={<Button>Continue</Button>}>++Your content here++</Admonition>+```++### Emphasis++#### Use bold, italics, and code for distinct purposes++Don't use them interchangeably or to add visual emphasis alone.++| Format | Use for |+| --------- | --------------------------------------------------------------- |+| **Bold** | A UI label, a term the reader must not miss, or an inline label |+| _Italics_ | A new term on first definition, or a title |+| `Code` | Anything typed, copied, or read literally by the system |++Bold covers the controls a reader interacts with, such as buttons, menu items, and+field names: `Click **Save**.` It also marks a term they can't afford to skip, as in+`**Never** commit your service role key.` The third case is the label opening a+paragraph or list item, as in `**Recommended**:`.++Use italics sparingly, and never for a UI label or for general emphasis. A title set in+italics by convention, such as a book or a third-party product, is the other case.++Code covers filenames, paths, commands, flags, environment variables, function and+parameter names, configuration keys, and literal values.++A command name is `code`, not **bold**, even though the reader also interacts with it.++Don't format for emphasis beyond these three. Screen readers announce text+modifications, so a sentence carrying several kinds of formatting is read aloud with the+formatting narrated between the words.++#### Name a control by its label++An icon has no accessible name a reader can match against what you wrote. Write `Click+**Notifications**` rather than `Click the bell icon`.++### Headings++#### Format headings in sentence case++Capitalize the first word and any proper nouns, and lowercase everything else: `Set up+authentication` rather than `Set Up Authentication`.++A heading can't carry meaning on its own. See+[`01-voice-and-tone.md`](./01-voice-and-tone.md).++Headings are also anchor targets. Other pages, `apps/www`, and Studio all deep-link into+guide anchors, so renaming a heading breaks those links. Moving a section or changing+its level preserves the anchor; only renaming breaks it.++### Lists++#### Choose the list type by whether order matters++Use an ordered list for steps taken in sequence, and an unordered list when order+doesn't matter. Use Arabic numerals (`1`, `2`, `3`) for ordered lists and dashes (`-`)+for unordered lists.++#### Prefer a paragraph to a single-item list++A list of one signals content that was meant to grow and didn't. Exceptions: layout+consistency across sibling sections, or an item that needs the visual separation.++#### Don't nest lists more than two deep++```md+1. List item+2. List item+ 1. List item+ 2. List item+3. List item+ - List item+ - List item+ <!-- DON'T ADD ANOTHER LEVEL OF NESTING -->+ - Overly nested list item+```++### Don't use these++#### Blockquotes++Use an admonition when the content needs emphasis, or prose when it doesn't.++#### Footnotes++Put the information in the sentence, or in a linked section when it's substantial enough+to need one.++## Steps and code++### Procedures++#### Use a procedure when a human or an agent must perform actions to reach an outcome++The format makes that expectation explicit.++Write sequential actions as an ordered list. **Begin each step with an imperative verb,+and include one action or a closely related set of actions per step.** Give the reader+enough context to know where to act.++For how many steps to present at once and when to split a procedure into phases, see+chunking in [`03-page-structure.md`](./03-page-structure.md).++An apparent one-step procedure can become two steps when there's a real orientation+action:++1. Open a terminal in your project directory.+2. Run `supabase start`.++The first step establishes the operating context for both readers and agents. Don't add+a redundant orientation step to a genuinely atomic instruction. Write `Click **Save**.`+rather than adding `Locate the **Save** button` as a separate step.++### Code blocks++#### Keep code lines short so the reader doesn't scroll++Split long shell commands with `\`.++JavaScript and TypeScript in code blocks are formatted by Prettier, and your pull+request is blocked from merging if the Prettier check fails. Run `pnpm format` from the+repository root, or set up automatic formatting in your editor.++#### Prefer lowercase for SQL++Write `select * from table` rather than `SELECT * FROM table`.++Optionally specify a filename after the language specifier:++````md+```ts environment.ts++```+````++Optionally highlight lines with `mark=${lineNumber}`:++````md+```js mark=12:13++```+````++### Tabs++#### Use tabs for alternative instructions across platforms or languages++The same task, done differently depending on the reader's stack. Don't use tabs for+sequential content or to hide information the reader needs either way.++The optional `queryGroup` prop lets a reader link directly to a tab, such as+`/docs/my-page?packagemanager=npm`.++```mdx+<Tabs scrollable size="small" type="underlined" defaultActiveId="npm" queryGroup="packagemanager">+<TabPanel id="npm" label="npm">++// ...++</TabPanel>+<TabPanel id="yarn" label="Yarn">++// ...++</TabPanel>+</Tabs>+```++## Data and diagrams++### Tables++#### Use a table when each row shares the same set of attributes++A part and its description, a type and when to use it, an if and a then. A table with+one populated column is a list.++Keep cells short. When a cell needs more than a sentence or two, the content probably+belongs in prose with the table reduced to a summary.++#### Introduce a table in the sentence before it++Not every screen reader announces that a table is coming. A reader can land in the first+cell with no idea what the rows hold.++#### Don't merge cells++A merged cell breaks the row-and-column relationship a screen reader uses to read a+table, so the reader loses track of which heading applies. If the content needs merged+cells, it needs two tables.++### Diagrams++#### Use a diagram to support the prose++A rendered diagram reaches fewer readers than the sentence next to it, so the text near+it has to carry the takeaway on its own. A reader using a screen reader, a reader on a+slow connection, and an agent reading the markdown export all depend on that sentence.++#### Every diagram needs `accTitle` and `accDescr`++Mermaid renders them into the SVG as `<title>` and `aria-labelledby`, which is what a+screen reader announces. Without them the diagram is an unlabeled graphic. `accTitle` is+one line naming what the diagram shows; `accDescr` describes the content, and takes a+braced block when it runs past one line. See the [Mermaid accessibility+options](https://mermaid.js.org/config/accessibility.html).++Write a fenced code block with `mermaid` as the language. The MDX renderer routes these+through the shared `Mermaid` component, so theming follows light and dark mode+automatically. For the full syntax, see the [Mermaid diagram+reference](https://mermaid.js.org/intro/syntax-reference.html).++````mdx+```mermaid+sequenceDiagram accTitle: Sign-in token exchange accDescr { A user clicks Sign in. The+browser requests authorization from Supabase, and Supabase returns a token to the+browser. }++participant User participant Browser participant Supabase++User->>Browser: Clicks "Sign in" Browser->>Supabase: Request authorization+Supabase->>Browser: Return token+```+````++- Put a standard Mermaid keyword, such as `sequenceDiagram`, `flowchart`, or+ `erDiagram`, on the first line. `flowchart` accepts a direction such as `LR` or `TD`.+- Write `accDescr` for someone who can't see the diagram. Name the nodes and the+ relationships between them. Restating the title tells that reader nothing.+- Keep each diagram focused on a single flow or concept. Split a dense diagram into+ smaller ones.+- Wrap node labels containing special characters in double quotes, including `*`, `/`,+ spaces, and punctuation: `A["content/**/*.md"]`.+- Don't hardcode colors. The component themes the diagram for both modes.++A diagram whose content can't survive being described in `accDescr` and the surrounding+prose is carrying too much. Split it, or replace it with a table.++## Media++### Images++#### Use an image when the reader needs to recognize something on screen++A dashboard control that's hard to describe in words is the usual case. Upload images to+`apps/docs/public/img`.++Use `.svg` for vector illustrations and `.png` for screenshots and other non-vector+graphics. Supported browsers receive `.webp` versions automatically.++#### Redact sensitive information++Remove API keys and any other secret visible in a screenshot before you upload it.++#### Write alt text that describes the image++A topic name is what the nearby heading already says. Describe what a reader who can't+see it would need: the labeled parts, the relationships between them, and any values it+carries.++#### Every image needs an `alt` attribute++Give a decorative image an empty one, `alt=""`, so a screen reader skips it rather than+reading a filename.++#### Never put new information only in an image++Whatever the image shows has to also exist in the text, because a reader who can't see+it has no other source.++#### Don't use an image of text, code, or terminal output++Use real text, which can be read aloud, searched, copied, and translated.++### Videos++#### Include a video as a table of contents video++Don't place a video in the main text. Define it in the page frontmatter:++```yaml+---+tocVideo: 'rzglqRdZUQE'+---+```++## Navigation++### Links++#### Link selectively++Every link is a decision the reader has to make, so a page dense with them costs more+attention than it saves. When a term needs one sentence of explanation, write the+sentence instead of sending the reader away. Link the same destination once per page,+unless the page is long enough that a reader is unlikely to have seen the first one.++#### Write link text that describes the destination++Use the target's title, or a phrase that names what the reader gets. The text has to+make sense read on its own, because assistive technology can list every link on a page+out of context.++- **Recommended**: `For more information about policies, see [Row Level Security](/docs/guides/database/postgres/row-level-security).`+- **Not recommended**: `For more information about policies, [click here](/docs/guides/database/postgres/row-level-security).`+- **Not recommended**: `See [this guide](/docs/guides/database/postgres/row-level-security).`++#### Put the identifying words first, and keep the text short++Use the shortest span that still describes the destination: `see the [reference+section](/link)` rather than `[see the reference section](/link)`.++#### Never use a bare URL as link text++Name the thing instead.++- **Recommended**: `[HTTP/1.1 RFC](https://www.rfc-editor.org/rfc/rfc2616)`+- **Not recommended**: `[https://www.rfc-editor.org/rfc/rfc2616](https://www.rfc-editor.org/rfc/rfc2616)`++#### Introduce a link with `see`, and say what the reader will find++Write `For more information about X, see Y` rather than `For more information on X, see+Y`. The `about` clause is what tells a reader whether the link is worth following.++#### Keep sentence punctuation outside the link++Write `see [Test your code](/link).` rather than `see [Test your code.](/link)`.++#### Say when a link does something the reader won't expect++A download, a new tab, or a jump within the page should be named in the link text or the+sentence around it.++#### Say when a link leaves Supabase docs++Name the destination in the sentence rather than relying on an icon: `see the Postgres+documentation on [row security+policies](https://www.postgresql.org/docs/current/ddl-rowsecurity.html)`.++#### Don't include the `https://supabase.com` origin++For pages on `supabase.com`, link with a path. Use a `/docs/...` path for a page in+Supabase docs, such as `[getting started](/docs/guides/getting-started)`. Use a+site-root path for a page outside docs, such as `[open the Supabase+Dashboard](/dashboard)`.++#### Link to a section with its anchor++Within a page, name the section: `see the [Links](#links) section of this document`.+Across pages, append the anchor to the path:+`[Chunking](./03-page-structure.md#chunking)`. Anchors come from heading text, so+renaming a heading breaks every link to it. See [Headings](#headings).++For when to cross-reference a section rather than repeat it, see [Navigation and+glue](./03-page-structure.md#navigation-and-glue).++### Content listings++#### Use a content listing on an overview or index page++A content listing holds a curated set of links, such as "Get started", "Next steps",+"Examples", or "Resources". Place the component inline in the guide MDX:++```mdx+<ContentListings id="storage-get-started" />+```++Use a partial only when the block is reused or gated with `$Show` at the partial level.+For an individual item that depends on a feature flag, set `feature` on the item rather+than wrapping the whole listing.++For the data file, ID uniqueness rules, and the test command, see+[CONTRIBUTING.md](../CONTRIBUTING.md).diff --git a/apps/docs/style-guide/03-page-structure.md b/apps/docs/style-guide/03-page-structure.mdnew file mode 100644index 00000000000..7e7ae1d0bd8--- /dev/null+++ b/apps/docs/style-guide/03-page-structure.md@@ -0,0 +1,317 @@+# How to structure a page++A well-structured document drastically reduces cognitive load. This document breaks down+how to segment information so it can be found at the right time and place.++_Chunking_ is a major principle of effective technical writing. Break things up. If+there are too many chunks, group the chunks, and maybe break up some more. We want to+avoid a "too long, didn't read" situation.++Apply this document when you add a page or move content around on an existing one.++| If you're deciding | Read |+| ------------------------------------------------------ | ------------------------------------------------------------- |+| Which document type to write, and how big it should be | [Document types](#document-types) |+| Which reader question a chunk answers | [Information types](#information-types) |+| How to order sections on the page | [Grouping sections](#grouping-sections) |+| How many items belong in one group | [Chunking](#chunking) |+| How to open a long page and connect its sections | [Navigation and glue](#navigation-and-glue) |+| How to keep a page from going stale | [Write timeless documentation](#write-timeless-documentation) |+| What to leave out of the repo | [Keep internal context out](#keep-internal-context-out) |++## Document types++Supabase docs contain five types of document. Decide which one you need before you start+writing.++| Type | Purpose | Contains | Doesn't contain | Example |+| --------------- | --------------------------- | ----------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------- |+| Explainer | Learn a topic | What it is, why, and when to use it | Instructions | [Auth architecture](/docs/guides/auth/architecture) |+| Tutorial | Finish a multi-feature goal | Procedures plus the reasoning | — | [Build a Next.js app](/docs/guides/getting-started/tutorials/with-nextjs) |+| Guide | Finish one task | Procedures in sequence | Background; link to an explainer | [Passwordless logins](/docs/guides/auth/auth-email-passwordless) |+| Reference | Look something up | Parameters, return types, samples | Context and use cases | [JavaScript client](/docs/reference/javascript/introduction) |+| Troubleshooting | Resolve one error | The symptom, the cause, the fix | Feature overviews | [Too many channels](/docs/guides/troubleshooting/realtime-too-many-channels-error) |++Reference content is generated from spec files rather than hand-authored. See+[CONTRIBUTING.md](../CONTRIBUTING.md) for the reference pipeline.++Troubleshooting entries live in `content/troubleshooting/` and use TOML frontmatter.+Some sync from GitHub discussions, so check whether an entry exists before writing one.++### Open a guide with a value statement++Name what the reader can do and why it matters to them. That's what tells a reader or an+agent whether the page matches their goal.++- **Recommended**: `Restrict access to a shared table with Row Level Security. To learn how a policy is evaluated, see [Row Level Security](...).`+- **Not recommended**: Several paragraphs about how Row Level Security works before stating what the reader can do.++Keep procedures focused on what the reader must do. Move substantial background into a+separate section or an explainer and cross-reference the authoritative explanation+rather than repeating it. This keeps the action path scannable and maintains one source+of truth.++### Topic size++Each type above is one unit of work for the reader. An explainer covers one topic. A+guide covers one targeted task. A tutorial covers one multi-feature goal. A reference+page covers one thing the reader looks up.++#### One unit per page++Enabling Row Level Security is one guide. Writing policies is a second, and designing a+multi-tenant schema is a third. A reader who lands on the page from search should be+able to finish what they came for. Link to the related pages.++#### Keep a short piece inside its parent++A fact or a principle is often one sentence. Put it in the section it qualifies. A+heading whose only job is to point somewhere else is a link.++#### Give the next unit its own page++Split when a section has grown its own subsections and shares little with the rest of+the page beyond the subject word. The new page takes the second task or the second+concept, and this page links to it.++[Chunking](#chunking) limits how many items sit in one group. Topic size limits what+those items are about. A procedure can have six steps and still cover two tasks.++- **Recommended**: A passwordless email login guide with `Send a one-time password` and `Verify the code`.+- **Not recommended**: An `Authentication` page that also covers passwords, OAuth, and session storage.++## Information types++The [Information+Mapping](https://support.informationmapping.com/hc/en-us/articles/213446789-Present-your-information-in-a-clear-and-consistent-way)+method names six types of information. Each answers a different reader question, and+each has a form that suits it.++| Type | Answers | Present with | Build it per |+| --------- | ------------------------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------- |+| Procedure | How do I do it? | Numbered steps, or an if/then table | [Procedures](./02-elements.md#procedures), [Tables](./02-elements.md#tables) |+| Process | What is happening? How does it work? | A stage-by-stage description, or a when/then table | [Tables](./02-elements.md#tables), [Diagrams](./02-elements.md#diagrams) |+| Structure | What are its parts? | A part and description table, or a labeled diagram | [Tables](./02-elements.md#tables), [Diagrams](./02-elements.md#diagrams) |+| Principle | What should I do or not do? | Text, a list, or an admonition | [Lists](./02-elements.md#lists), [Admonitions](./02-elements.md#admonitions) |+| Concept | What is it? | Text, a list, or a diagram | [Lists](./02-elements.md#lists), [Diagrams](./02-elements.md#diagrams) |+| Fact | What are the facts? | Text, a list, or a table | [Lists](./02-elements.md#lists), [Tables](./02-elements.md#tables) |++### Classify the content++1. Split the content into chunks. One chunk is one thing you're telling the reader.+2. For each chunk, ask which reader question it answers, and read its type off the+ table above.+3. Build each chunk in the form its `Present with` column names. A chunk already in a+ different form is a defect. Fix it.+4. Group the chunks by type, per [Grouping sections](#grouping-sections).++[Example](#example) below works one paragraph through these steps.++### Separating the types++#### Separate a procedure, a process, a structure, or a concept++Each usually reads better in its own section. Procedure and process get blended most+often, because both answer a question about how, and a reader following steps can't act+on the process sentences.++#### Keep context out of the action path++A concept or a process tends to work better before the procedure or after it than+threaded through the steps.++#### Let a principle or a fact ride along++Either is often a single sentence, so it can sit in the section it qualifies rather than+getting one of its own. A fact about timing fits in the step it describes, and a+principle can close the concept paragraph that motivates it.++#### Look again at a long paragraph++Past three or four sentences, it has often picked up a second kind of information. Label+each sentence and see where the labels change.++#### Leave connective prose alone++An introduction, a transition, an outcome, and a navigation outline describe the page+rather than the product, so none of this applies to them.++### Example++Not recommended, because one paragraph blends a concept, a procedure, and a structure:++```md+Row Level Security is a Postgres feature that restricts which rows a user can read+or write, and it's the main way to secure a table that several users share. Enable+it by running `alter table profiles enable row level security`, which takes effect+immediately. Be careful, because a table with Row Level Security enabled and no+policy returns no rows to every client, so write a policy before you deploy. The+`using` clause of a policy accepts any expression that returns a boolean.+```++Recommended, with each type in the presentation that suits it:++```md+## Row Level Security++Row Level Security restricts which rows a user can read or write. It's the main way+to secure a table that several users share.++### Enable Row Level Security++1. Run `alter table profiles enable row level security`. The change takes effect+ immediately.+2. Write a policy that grants the access your app needs.++<Admonition type="caution">++A table with Row Level Security enabled and no policy returns no rows to `anon` or+`authenticated`. Write a policy before you deploy.++</Admonition>++### Policy reference++The `using` clause accepts any expression that returns a boolean.+```++## Grouping sections++Information types apply at the page level too. Group sections of related types together,+and keep the procedure group unbroken so context doesn't interrupt the action path.++### Classify a section by what the reader is doing in it++On a page about tables every section is about tables, so subject matter tells you+nothing. A reader opens a section on schemas to understand something, so it's context.++### Split a section that serves two types++Filing it under the larger half buries the other one. Give the new half a heading, keep+the heading text of the half that stays, and cross-reference the two.++One order that works: a short concept opener, then procedures, then concept and process,+then structure and fact.++```text+## What is a table? <- concept opener+## Creating and managing tables <- procedures+### Creating tables+### Securing your tables+### Loading data+## How tables are organized <- concept and process+### Primary keys+### Relationships between tables+### Schemas+## Reference <- structure and fact+### Data types+```++### Chunking++Apply the [Information Mapping chunking+principle](https://informationmapping.com/blogs/news/writing-for-the-web-the-magical-number-seven-plus-or-minus-two):+present 5 ± 1 related items at a time. That gives readers a manageable chunk of four to+six. Aim for the lower end when the task is complex or unfamiliar.++Information Mapping gives 7 ± 2 as the general limit and 5 ± 1 for content read on a+screen. Screen reading is less accurate than the same content on paper. Supabase docs+are read on a screen, so 5 ± 1 applies.++If a procedure has more than six steps, group related steps into named phases or smaller+procedures. Don't add steps to reach a minimum. The range organizes information.++The same limit applies to sections in a group. A page with ten top-level headings needs+grouping. Reordering them changes nothing.++Headings and lists are the other half of chunking. A long stretch of prose with no+heading gives a reader no way in and no way to skip. A reader navigating by heading has+nothing to navigate. Where a paragraph has grown past its one topic, a heading or a list+usually serves better than a longer paragraph.++A lookup surface is the exception. When a reader arrives to find one entry rather than+to read the page, the entries carry their own order: alphabetical, or the order of an+API. Grouping them into fives would hide what they came for.++A reference document is the same case. A reader opens this style guide to find one rule.+Its sections are a list to scan, not a sequence to hold in memory.++For how to format the steps inside a procedure, see+[`02-elements.md`](./02-elements.md).++## Navigation and glue++### Begin a long guide with a short outline of its major section groups++Link to each group and say when a reader should use it. Don't add section navigation to+a short guide when its headings already fit on one screen.++```md+Connect your app to Postgres through a connection pooler, a direct connection, or a+Supabase client library.++- [Choose a connection method](#choose-a-connection-method) compares the options and+ their trade-offs. Start here if you aren't sure which one fits your app.+- [Connect your app](#connect-your-app) has the steps for each method.+- [Connection parameters](#connection-parameters) lists every parameter and its+ default.+```++Each link says what the reader gets from that group, so someone who already knows which+method they want goes straight to the procedures.++### Connect contextual sections to their procedures++Do this when the relationship helps readers navigate. Add a brief introduction to each+section group, a transition when the information type changes, and an outcome after a+procedure. Add links selectively rather than linking every adjacent section.++- Group introduction: `The following sections cover each connection method in turn. Every method needs your project reference, which you find on the project settings page.`+- Transition where the type changes: `Those are the mechanics of opening a connection. To understand why a pooled connection behaves differently under load, see [Connection pooling](...).`+- Outcome after a procedure: `Your app now connects through the pooler. Queries that used to fail at the connection limit queue instead.`++## Write timeless documentation++Document the product as it is now. Language that fixes a page to a moment goes stale,+and a reader can't tell whether `currently` was written last week or three years ago.++### Avoid words that anchor a sentence to a point in time++| Avoid | Avoid | Avoid |+| ------------------ | --------------------- | --------------------- |+| as of this writing | existing | now |+| currently | future, in the future | old, older |+| does not yet | latest | presently, at present |+| eventually | new, newer | soon |++[`WORD_LIST.md`](./WORD_LIST.md) has entries for the two that come up most,+[currently](./WORD_LIST.md#currently) and [latest, new, and+soon](./WORD_LIST.md#latest-new-and-soon).++- **Recommended**: `The emulator supports the following filters.`+- **Not recommended**: `The emulator now supports the following filters.`++### Don't promise a feature that hasn't shipped++`Coming soon`, `will be available`, and `once finalized` all decay into inaccuracy, and+a reader can't act on any of them. When a phased rollout is real, state the criteria+that decide who has it: `Available to organizations on Pro and Enterprise plans`.++### Don't ship a placeholder page++A page saying `This is a placeholder` or `More details coming soon` promises content on+no schedule. Wait until the page is worth reading, or ship the smaller thing that's true+today. When navigation structure forces a page to exist, link out to resources that are+complete.++### Exceptions++Changelog, release notes, and blog content are time-sensitive by nature, and referencing+the future is their job. Procedural content can use a time word for a state change the+reader causes: `The table now appears in the editor.`++## Keep internal context out++Supabase docs are open source. Keep planning notes, unshipped features, business intent,+and references to ticketing systems out of the repo. Put review-time context in the pull+request description and product context in the team's project-management tool.diff --git a/apps/docs/style-guide/README.md b/apps/docs/style-guide/README.mdnew file mode 100644index 00000000000..adb16c9d031--- /dev/null+++ b/apps/docs/style-guide/README.md@@ -0,0 +1,64 @@+# Supabase documentation style guide++Welcome to the documentation style guide. This is a living document that+serves as the evolving source of truth for:++- Our Supabase voice and our audience+- The structure of our technical documents+- How we consistently talk about our product++This guide is for everyone who is writing to help Supabase users. It+can be used by anyone who writes for Supabase, no matter your role or whether you are an employee or open+source contributor.++The style guide is also for both humans and LLMs: our [SKILLS](../CONTRIBUTING.md#write-the-docs-skills)+use the style guide, but the style guide is also human-readable and friendly. Much of this guide is dedicated to removing AI smells such as verbosity and overused+asides.++We encourage you to contribute to the style guide so that we write the best+documentation for Supabase. If something consistently bothers you, it may bother others as+well. That could be an inconsistently used term or an unnecessarily verbose writing+pattern. Open a style guide PR and start the discussion.++## Navigation++The files in the style guide are numbered in the order of content size. It starts with+the smallest piece, at the word level, then progresses to the sentence, the element,+and the whole page. `WORD_LIST` is unnumbered and a master document for our word+consistency decisions.++| File | Covers |+| ------------------------------------------------ | -------------------------------------------------- |+| [`WORD_LIST.md`](./WORD_LIST.md) | Terminology, spelling, capitalization |+| [`01-voice-and-tone.md`](./01-voice-and-tone.md) | Person, tense, sentence length, brevity |+| [`02-elements.md`](./02-elements.md) | Admonitions, code blocks, procedures, tabs, images |+| [`03-page-structure.md`](./03-page-structure.md) | Document type, section grouping, chunking |++## Before you open a pull request++Always run [`WORD_LIST.md`](./WORD_LIST.md) against the finished page. We removed any+linter and instead entrust you to use the word list.++You can run `/review-the-docs` for a local self-review, and `/test-the-docs` if the page+contains runnable snippets.++### If you drafted with an agent++Run a critic pass. Open a+subagent with a clean context, holding only the relevant guide files and the draft+text, and give it this instruction:++> Referencing the docs style guide, cite every rule violation in the draft. Quote+> the offending phrase and cite the rule it breaks as `file#anchor`, for example+> `03-page-structure.md#chunking`. Derive the anchor from the heading itself, and+> ignore headings inside fenced code blocks, which are examples rather than rules.+> Then resolve.++Each citation has to resolve to a real heading in the guide. One that doesn't is an invented rule, so check the citations before you act on them.++## References++- For spelling, see [Merriam-Webster.com](https://merriam-webster.com)+- For accessible writing, see [Google's accessibility guidance](https://developers.google.com/style/accessibility)+- For gaps, see [Google developer documentation style guide](https://developers.google.com/style)+- For an additional developer guide reference, see [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)diff --git a/apps/docs/style-guide/WORD_LIST.md b/apps/docs/style-guide/WORD_LIST.mdnew file mode 100644index 00000000000..ae05cb3ecf6--- /dev/null+++ b/apps/docs/style-guide/WORD_LIST.md@@ -0,0 +1,989 @@+# Word list++Preferred spelling, capitalization, and usage for terms in Supabase docs including Supabase+product names. Use your best judgement when applying these rules. They are not intended+to be strict, one-size-fits-all solutions and can evolve with your input. Feel free+to contribute to this list as you write your documentation.++This list is part of the [style guide](./README.md). It is the source of truth for all+documentation consistency.++## Use with an AI agent++To apply this word list with an agent, you can use one of our skills. For more information, see [Write the docs skills](../CONTRIBUTING.md#write-the-docs-skills).++**For agents:** Work in two passes rather than reading this file end to end.++1. Mechanical pass. Read [Phrase groups](#phrase-groups). It collects every literal+ term list in one place, so you can match it against the page in a single read.+2. Judgment pass. Run `grep '^### ' WORD_LIST.md` for the term index, then read only+ the entries that match words on the page. Most entries carry a condition, so read+ the entry before you change a word.++After you draft, run the mechanical pass again in a fresh context to prevent drift.++## 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.`.++### 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.++### agent++Use _agent_ for a system that uses a model and tools to take actions, such as+following a procedure or drafting a page. Lowercase _agent_ unless it is a product+name.++Use _AI agent_ the first time _agent_ could mean a person or an HTTP user agent.+After that, use _agent_.++Use _LLM_ for the model itself. See [LLM](#llm).++### AI++You can use _AI_ without spelling out _artificial intelligence_ when the audience+is familiar with the term. For the model, see [LLM](#llm). For a system that uses+a model and tools to act, see [agent](#agent).++### 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_.+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.++### 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. See+[Write timeless documentation](./03-page-structure.md#write-timeless-documentation).++## 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. Don't use _easy_, _easily_, _quickly_,+_simple_, or _simply_.+++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_).++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.++### 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.++## 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. See+[Write timeless documentation](./03-page-structure.md#write-timeless-documentation)+for the full list of words that fix a page to a moment.++### leverage++Use _use_ or a more specific verb instead of _leverage_.++### lifecycle++Write _lifecycle_, not _life cycle_ or _life-cycle_.++### LLM++Use _LLM_ for the model that reads or generates text. When a page introduces the+term, spell it out once as _large language model (LLM)_, then use _LLM_.++Use _agent_ for a system that takes actions with tools. See [agent](#agent).++### login and log in++Don't use _login_ or _log in_ in prose. Use _sign in_. See+[sign in and sign-in](#sign-in-and-sign-in).++## M++### marketing language++Describe measurable behavior instead of making promotional claims. Don't use:++- _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++Spell out zero through nine. Use numerals for 10 and greater. Use numerals+regardless for versions, technical quantities, step and page numbers, prices, and+percentages, and throughout a sentence that mixes a number under 10 with a larger+one.++- **Recommended**: four options, 24 hours, version 3, 128 bits, step 2, 40%+- **Not recommended**: 4 options, twenty-four hours++Spell out ordinals. Group digits in large numbers with commas, counting left from+the decimal point. Write fractions as decimals where practical. Use a hyphen with+no spaces for a range.++- **Recommended**: first, forty-third, 1,532,784 bytes, 0.75, 2012-2016+- **Not recommended**: 1st, 1532784 bytes, three-quarters, 2012 - 2016++Omit a count of steps or items unless the count helps the reader plan. Name the+action or link the heading rather than citing a step or section number.++- **Recommended**: To connect to your database:+- **Recommended**: After you create the project, copy the project URL.++### 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.++### 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.++### 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.++### powered by++Don't use _powered by_. Prefer _with_, _by_, or _through_, depending on the+relationship.++### prior to and subsequent to++Use _before_ and _after_.++## 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.++### sign in and sign-in++Use _sign in_, _sign out_, and _sign up_ as verbs. Use the hyphenated forms+_sign-in_, _sign-out_, and _sign-up_ as nouns or adjectives. Match the product UI+labels **Sign in**, **Sign out**, and **Sign up**.++Keep _login_, _log in_, _logout_, _log out_, and `logOut` when quoting+third-party UI or when they are part of code, routes, URL slugs, CLI commands, or+established feature names such as _social login_.++### singular they++Use _they_, _them_, and _their_ as gender-neutral singular pronouns. Don't use+_s/he_, _he/she_, _(s)he_, or _him/her_.++### slang abbreviations++Don't use internet slang in documentation, such as _tl;dr_, _ymmv_, _rtfm_, _imo_,+or _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_, not _utilize_ or _utilise_. Use _utilization_ only when referring to the+measured proportion of a resource in use.++## V++### vague verbs++Describe the concrete action:++- _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.++### vCPU++Use _vCPU_ (plural _vCPUs_) for the CPU resources of Supabase compute sizes.+Don't describe Supabase compute in _cores_.++_Core_ remains correct for hardware the reader owns or manages, such as+self-hosting requirements or a migration VM, and in general CPU discussion.++- Recommended: The 16XL compute size has 64 vCPUs.+- Recommended: Run the migration from a VM with 8 CPU cores.+- Not recommended: The 16XL compute size has 64 cores.++### 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_.++### 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.++## Phrase groups++The alphabetical entries explain the intent behind each rule. This section collects+the full term lists in one place, grouped by the problem they cause.++Every heading here is prefixed with `Group:`, so `### Group:` selects the whole set.+Where a group entry and its alphabetical entry differ, the alphabetical entry governs.++### Group: Filler++Don't use _actually_, _easily_, _easy_, _just_, _let's_, _obviously_,+_of course_, _please_, _quickly_, _simple_, _simply_, or _that's it_. Remove the term or state the intended meaning directly.+_please_ is the exception: keep it when asking permission, apologizing for an+inconvenience, or requesting an action that primarily benefits Supabase.++### Group: Marketing language++Don't use _best in class_, _best-in-class_, _cutting edge_,+_cutting-edge_, _effortlessly_, _game changer_, _game-changer_, _hassle free_,+_hassle-free_, _powerful_, or _seamlessly_. Describe specific behavior or+measurable results instead.++### Group: Vague verbs++Use _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 none of these match the operation.++### Group: Apologies++Don't use _oops_ or _sorry_. State what happened directly. Apologize+only when an apology is genuinely useful to the reader.++### Group: First person++Don't use _I_, _I'm_, _me_, _my_, or _mine_. Address the+reader as _you_ and use an explicit noun for other actors. Use _we_ only when it+clearly refers to Supabase. See [first person](#first-person) for the full rule.++### Group: Gender-neutral pronouns++Don't use _s/he_, _he/she_, _(s)he_, or _him/her_. Use the+singular _they_ or rewrite the sentence.++### Group: Inclusive language++Don't use these terms:++- _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++### Group: Abbreviations++Write _e.g._ with both periods, not _eg._ or _eg_. Replace _i.e._, _ie._, and+_ie_ with _that is_. Prefer _for example_ and _that is_ in prose when space+allows. See [abbreviations](#abbreviations) for when to spell one out on first use.++### Group: Powered by++Don't use _powered by_. Use _with_, _by_, or _through_, depending on the+relationship.++### Group: Preferred usage++Use:++- _Postgres_ for _PostgreSQL_+- _concurrent connections_ for _concurrent clients_+- _use_ for _utilize_ and _utilise_+- _uses_ for _utilizes_ and _utilises_+- _using_ for _utilizing_ and _utilising_++### Group: Direct, concise language++Don't use 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_++### Group: Internet slang++Don't use _tl;dr_, _ymmv_, _rtfm_, _imo_, or _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](https://creativecommons.org/licenses/by/4.0/).+See the+[Google developer documentation style guide word list](https://developers.google.com/style/word-list)+for the original work. Supabase-specific guidance and adaptations are maintained+in this repository.