docs: Prisma ORM 8 docs audit, personas, journeys, and proposed IA (for discussion)

[wmadden-electric]

Most complaints about the Prisma ORM 8 docs come from two kinds of reader, and the site's entry points are built for a third:

The Newcomer   has an app already, wants typed queries; lands on pages that scaffold a new app for them
The Upgrader   has a Prisma ORM 7 app and a database with data; finds no page that says what moved or whether to move
The Builder    wants to ship on the platform with an agent's help; the root page, the agent prompts, and the tutorial are theirs

What this PR is

Draft, for discussion, not for merge as-is: the design documents behind the Prisma ORM 8 docs work, added under docs/orm-docs-audit/ so they can be read and commented in one place. They describe readers, the jobs those readers come to do, the mental model pages should be written from, the proposed information architecture, and the reasoning. They are design documents, not status: they describe the target and why, and do not track progress.

The decision they build up to

Serve the Newcomer and the Upgrader before the Builder at the ORM entry points, and organise the Getting Started > Prisma ORM subtree by the reader's starting state rather than by which tool runs:

1. New app from scratch
2. App already started, empty database
3. Existing database with data
4. Existing Prisma ORM 7 app

Each door is one page that carries the whole path. Two pages the Upgrader needs are added at the top level: "Coming from Prisma ORM 7" and "Release status". The /orm page shows the product (a contract, the query it enables, the typed result) instead of arguing for the design against Prisma ORM 7. Everything below the entry points (Data Modeling, Contract Authoring, Fundamentals, Migrations, Middleware, Extensions, Reference) stays where it is.

Reading order

1. README.md, then personas.md: the four readers.
2. journeys.md: ten jobs, each with what done looks like, what the docs must provide, and where the structure fails it.
3. mental-model.md: the first-principles explanation (contract versus schema, emit, signature, plans, migrations and refs) that pages get written from.
4. ia.md: the proposed sidebar trees and /orm page, then the current state and the reasons.
5. changes.md: every proposed change by kind, with the recommended order and the decisions that need an owner.
6. naming.md, the three briefs handed to ORM-side agents, and audit/, the page-by-page findings with a source citation for every claim.

What is already settled, and what is open

Settled: the readers and their order of priority; the naming rule (the product is Prisma ORM; a version number only when contrasting versions); the mental model as the source pages are written from; correcting the published pages before restructuring (done in #8236, #8237, #8238).

Open, and the reason this PR exists: the four-door structure of the ORM entry, the rewritten /orm page, and where the Prisma ORM 8 guides tree goes once the Prisma 7 guides have moved.

Alternatives considered

• Restructure first, correct pages after. Rejected: readers were copying broken samples every day; corrections were mechanical and did not depend on the structure.
• Organise the entry by database (PostgreSQL, MongoDB) at the top level. Rejected: the reader knows their starting state before they know which tool runs; the database split stays inside each door.
• Keep the design in a shared document outside the repo. Rejected: the documents cite file paths and source lines, and reviewers are engineers who will read them next to the pages.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
blog	Ready	Preview	Sep 16, 2026 9:22am UTC
docs	Ready	Preview	Sep 16, 2026 9:22am UTC
eclipse	Ready	Preview	Sep 16, 2026 9:22am UTC
site	Ready	Preview	Sep 16, 2026 9:22am UTC

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}

[ankur-arch]

love this!