chore(docs): revise CONTRIBUTING for common pitfalls with Information types (#50357)

## Problem

Our CONTRIBUTING and WORD_LIST is doing a pretty good job at improving
contributor documentation, but I consistently see some issues:
- **Uses "This guide":** "This guide..." is no longer recommended based
on discussions with Nik. Instead, recommendation is to omit those words
while still including a value statement. I still do not recommend
including a definition of the title term as an opening sentence.
- **Mixed information types:** I still often see mixed information types
or wordy, chunky paragraphs. Without a definition in place, my agent
mistakenly thought there was just "Procedure, Context, and Reference."

## Solution

- **A new Information types section** that clearly outlines definitions
and usage with cross-references so that this guidance is not easily
missed.
- **Removed "This guide"** recommendation in favor of a value statement.

Additionally added a clear rule about how to spell numbers consistently
and gave more guidance about how to structure a large topic.

## Manual testing

1. Open
[apps/docs/CONTRIBUTING.md](https://github.com/supabase/supabase/blob/docs/value-statements-and-counts/apps/docs/CONTRIBUTING.md)
on this branch. The Information types section renders its table, the
Recommendations list, and both fenced examples.
2. Click the two `Information types` links, one in General principles
and one under Guides. Both jump to the section.
3. Open
[apps/docs/WORD_LIST.md](https://github.com/supabase/supabase/blob/docs/value-statements-and-counts/apps/docs/WORD_LIST.md).
The `numbers` entry sits under N, ahead of `numbers in product
versions`.
4. Run `npx prettier --check apps/docs/CONTRIBUTING.md
apps/docs/WORD_LIST.md` from the repo root. It reports no formatting
changes.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Documentation**
- Expanded the contribution guide with Information Mapping guidance for
procedures, processes, principles, concepts, structures, and facts.
- Clarified paragraph and section grouping, page-level classification,
recommended ordering, navigation, transitions, outcomes, and connective
prose.
- Added guidance to use value-focused introductions and bold
“Recommended” and “Not recommended” labels.
- Added number-formatting guidance, including numeral usage, ranges,
fractions, and when to omit step or item counts.
  - Updated related entries in the documentation word list.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

apps/docs/CONTRIBUTING.md

@@ -15,10 +15,72 @@ To make docs as clear as possible:
 - Write for the user. Think about what task they want to complete by reading your doc. Tell them what, and only what, they need to know.
 - Write like you talk. Conversational English is easier for a global audience to understand and localize. Many readers who use English as an additional language learn conversational rather than academic English. Use words and sentences that sound natural when speaking. Cut unnecessary words. Read your writing out loud to help you choose the clearest and simplest phrases.
 - Prefer short, direct sentences. Express one relationship at a time, and avoid unnecessary compound structures. This makes each sentence easier to understand, localize, and interpret consistently.
-- Cover one topic in each paragraph. Start a new paragraph whenever you change the topic. Don't worry about paragraphs being too short.
+- Cover one topic in each paragraph. Start a new paragraph whenever you change the topic, or when you move between [information types](#information-types). Don't worry about paragraphs being too short.
 - Avoid using idioms and colloquialisms, such as `piece of cake`. These phrases are often specific to a region or culture.
 - Refer to the reader as `you`. Don't use `we` to refer to the reader. Use `we` only to refer to the Supabase team.
 
+## Information types
+
+Separating kinds of information helps a reader reach what they came for and retain it afterward. Someone scanning for a command shouldn't have to read past a definition to find it, and someone reading to understand shouldn't have to step around instructions. Blended prose slows down both, along with an AI agent trying to answer a question from the page, and little of it sticks.
+
+The [Information Mapping](https://support.informationmapping.com/hc/en-us/articles/213446789-Present-your-information-in-a-clear-and-consistent-way) method names six kinds, each answering a different reader question:
+
+| Type | Answers | Present with |
+| --- | --- | --- |
+| Procedure | How do I do it? | Numbered steps, or an if/then table |
+| Process | What is happening? How does it work? | A stage-by-stage description, or a when/then table |
+| Structure | What are its parts? | A part and description table, or a labeled diagram |
+| Principle | What should I do or not do? | Text, a list, or an admonition |
+| Concept | What is it? | Text, a list, or a diagram |
+| Fact | What are the facts? | Text, a list, or a table |
+
+### Recommendations
+
+- **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.
+
+### Examples
+
+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 every
+client. Write a policy before you deploy.
+
+</Admonition>
+
+### Policy reference
+
+The `using` clause accepts any expression that returns a boolean.
+```
+
 ## AI agent skills for docs authoring
 
 If you're using an AI coding agent that reads `.agents/skills/`, such as Claude Code, Cursor, or Codex, invoke skills with `/name`, for example `/write-the-docs`. The canonical files live in `.agents/skills/` (`.claude/skills` is a symlink).
@@ -41,7 +103,7 @@ Use [`edit-the-docs`](../../.agents/skills/edit-the-docs/SKILL.md) for style, st
 
 ## Document types
 
-Supabase docs contain 4 types of documents. Before you start writing, think about what type of doc you need.
+Supabase docs contain four types of documents. Before you start writing, think about what type of doc you need.
 
 ### Explainers
 
@@ -70,19 +132,56 @@ Guides are also goal-oriented, but they focus on shorter, more targeted tasks. F
 
 Guides contain mostly procedures: concise steps that readers can follow in sequence.
 
-Begin each guide with a sentence that declares its intent, such as `This guide explains how to set up email login.` This helps readers and agents confirm that the guide matches their goal and expected outcome.
+A value statement makes a good opener: 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.
 
 Keep procedures focused on what the reader must do. Move substantial background or conceptual explanations into a separate section or an explainer. Cross-reference the authoritative explanation instead of repeating it in the procedure. This keeps the action path scannable, gives readers optional depth, and maintains one source of truth.
 
-- Recommended: `This guide explains how to enable Row Level Security. To learn how Row Level Security controls access, see [Row Level Security](...).`
-- Not recommended: Begin with several paragraphs about how Row Level Security works before stating what the guide helps the reader do.
+- **Recommended**: `Restrict access to a shared table with Row Level Security. To learn how a policy is evaluated, see [Row Level Security](...).`
+- **Not recommended**: Begin with several paragraphs about how Row Level Security works before stating what the reader can do.
 
-**Mixed information types:** When a guide contains substantial context or reference material, group sections by information type. Keep contextual and reference sections separate from the procedure group so that background information doesn't interrupt the action path.
+**Mixed information types:** [Information types](#information-types) apply at the page level too. Group sections of related types together, and try to keep the procedure group unbroken so context doesn't interrupt the action path. A section serving two types can be split, with a cross-reference between the halves.
+
+Classify a section by what the reader is doing in it, not by what it's about. 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.
+
+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
+```
 
 **Navigation:** Begin a long guide with a short outline of its major section groups. Link to each group and state when a reader should use it. Don't add section navigation to a short guide when the headings are already easy to scan.
 
+For example, an introduction to a long guide that mixes information types:
+
+```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.
+
 **Cross-references and glue:** Connect contextual sections to their corresponding procedures 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.`
+
 For inspiration, see [an example of a guide](/docs/guides/auth/auth-email-passwordless).
 
 ### Reference
@@ -203,8 +302,8 @@ Begin every admonition with its impact and purpose: the "so what." Use the first
 
 For example:
 
-- 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.`
+- **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.`
 
 Choose the appropriate `type` for your admonition:
 
@@ -267,7 +366,7 @@ Optionally highlight lines by using `mark=${lineNumber}`.
 
 Use **bold**, _italics_, and `code` formatting for distinct purposes. Don't use them interchangeably or to add visual emphasis alone.
 
-- **Bold**: Mark UI labels the reader interacts with, such as buttons, menu items, and field names. For example, `Click **Save**.` Also use bold for a term the reader must not miss, such as `**Never** commit your service role key.`
+- **Bold**: Mark UI labels the reader interacts with, such as buttons, menu items, and field names. For example, `Click **Save**.` Also use bold for a term the reader must not miss, such as `**Never** commit your service role key.` Bold is also the convention for an inline label that opens a paragraph or a list item, such as `**Recommended**:` or `**Navigation:**`.
 - _Italics_: Introduce a new term the first time you define it, or reference a title, such as a book or a third-party product name written in italics by convention. Use italics sparingly. Don't use italics for UI labels or for general emphasis.
 - `Code`: Mark anything the reader types or copies verbatim, or anything the system reads literally. This includes filenames, paths, commands, flags, environment variables, function and parameter names, configuration keys, and literal values. For example, `` Set `SUPABASE_URL` in your `.env` file. ``
 

apps/docs/WORD_LIST.md

@@ -20,8 +20,8 @@ meaning.
 
 Don't use `+` to mean _or later_.
 
-- Recommended: Postgres 15 or later
-- Not recommended: Postgres 15+
+- **Recommended**: Postgres 15 or later
+- **Not recommended**: Postgres 15+
 
 ### `&`
 
@@ -71,9 +71,9 @@ is familiar with the term.
 Use _allowlist_ and _denylist_ as nouns. Prefer a precise verb that describes the
 action instead of using either term as a verb.
 
-- Recommended: Allow requests from the IP address.
-- Recommended: Add the IP address to the allowlist.
-- Not recommended: Allowlist the IP address.
+- **Recommended**: Allow requests from the IP address.
+- **Recommended**: Add the IP address to the allowlist.
+- **Not recommended**: Allowlist the IP address.
 
 Don't use _blacklist_ or _whitelist_. The linter reports these terms as errors.
 When a literal code item contains one of them, format the item as code and explain
@@ -83,9 +83,9 @@ what it does.
 
 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.
+- **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
 
@@ -265,9 +265,9 @@ _disabled_ to mean that something is broken or unavailable.
 
 _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.
+- **Recommended**: The Dashboard displays the query results.
+- **Recommended**: The query results appear.
+- **Not recommended**: The query results display.
 
 ### docs
 
@@ -400,8 +400,8 @@ is clearer.
 
 Use _impact_ as a noun. Prefer _affect_ as the verb.
 
-- Recommended: The change affects performance.
-- Not recommended: The change impacts performance.
+- **Recommended**: The change affects performance.
+- **Not recommended**: The change impacts performance.
 
 ### index
 
@@ -455,8 +455,8 @@ literal commands, signals, and established technical operations.
 
 Use _later_ and _earlier_ for version ranges.
 
-- Recommended: Version 2.2 or later
-- Not recommended: Version 2.2 or higher
+- **Recommended**: Version 2.2 or later
+- **Not recommended**: Version 2.2 or higher
 
 ### latest, new, and soon
 
@@ -528,6 +528,29 @@ Use _Multigres_ for the product name. Don't write _multi-gres_ or _MultiGres_.
 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_,
@@ -563,9 +586,9 @@ memory_, or _handles more concurrent connections_.
 
 Avoid using _persist_ as a transitive verb.
 
-- Recommended: Store the session.
-- Recommended: Make the session persistent.
-- Not recommended: Persist the session.
+- **Recommended**: Store the session.
+- **Recommended**: Make the session persistent.
+- **Not recommended**: Persist the session.
 
 ### plain text and plaintext
 
@@ -653,8 +676,8 @@ risk or control.
 
 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.
+- **Recommended**: Complete the setup to set up authentication.
+- **Not recommended**: Setup authentication.
 
 ### shard
 
@@ -694,9 +717,9 @@ examples unless uppercase is required by the surrounding convention.
 
 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.
+- **Recommended**: Connect to the server by using SSH.
+- **Recommended**: Use the `ssh` command.
+- **Not recommended**: SSH into the server.
 
 ### startup and start up
 
@@ -732,8 +755,8 @@ either form with `3rd`.
 
 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.
+- **Recommended**: This setting controls connection pooling.
+- **Not recommended**: This controls connection pooling.
 
 ### timeout and time out