docs-writer

# Docs Writer Write documentation a developer can follow from start to finish without getting stuck or guessing. Every page answers three questions, in this order: what am I doing, why does it matter, and what do I do next. If a rule here conflicts with house style, follow the house style and flag the conflict to the operator. For a step-by-step example of writing each kind of page (how-to, concept, reference) and rewriting an existing one, see `references/how-to-use.md`. For a Prisma 8 docs page or section (anything under `content/docs/orm/` outside `v6/` and `v7/`, or the Prisma 8 getting-started pages under `content/docs/(index)/`), also read `references/prisma-8.md`: page location, redirect handling (commented out until the URL cutover), tested-example requirements, tab and diagram conventions, and naming rules. ## Foundation These come from Prisma's positioning. They shape how docs frame the product, without turning a page into marketing. - **Prisma is one integrated platform, not three separate tools.** Prisma 8, Prisma Postgres, and Prisma Compute are built to work together for TypeScript teams. When a page spans more than one, show how they connect; the integration is the reason to use them together, so make it the spine of the page rather than a footnote. - **Write for a TypeScript developer, often one building with an AI coding agent.** They want fewer moving parts and a working path, not a tour of features. - **Be honest about maturity.** Don't claim general availability or production readiness for early-stage products (Prisma Compute is early-stage). Don't call a product best-in-class or claim feature parity across products. When the source material is unsure, use narrower wording and flag it. ## Before you write Answer these four questions. If you can't, find the answer before drafting. - **Who is the reader, and what do they already know?** A backend developer new to this product needs different framing than someone migrating from a competitor. Write for one reader. - **What one task does this page complete?** One page, one task. If you're documenting two tasks, write two pages and link them. - **What does the reader need set up before step 1?** List exact prerequisites: account, runtime version, installed CLI, env vars. - **How will the reader know it worked?** Decide the success signal now. You'll end the page with it. ## Page shape Use this structure for a how-to or quickstart. Drop any section that doesn't apply. Don't add sections for ceremony. 1. **Title**: name the task as a verb phrase. "Deploy a Prisma Compute app", not "Deployment". 2. **Intro (1-2 sentences)**: state what the reader will have done by the end, and the one reason it matters. 3. **Prerequisites**: a bulleted list with exact versions and links. The reader should clear this list in under a minute. 4. **Numbered steps**: see "Writing a step". 5. **Verify**: a command the reader can copy and run, with the exact expected output. "You should see your app respond" is not a verification; `curl https://your-app.url` returning `{"status":"ok"}` is. 6. **Next steps**: one to three links to the obvious follow-on tasks. A numbered step must require the reader to do something: run a command, edit a file, click a button. If there's no action, it's a note, not a step. Put it inline as a short callout instead of numbering it. ## Other page types A how-to gets the reader through a task. Two other types come up often. Same voice, same slop rules; different spine. **Concept page** explains one idea so the reader can make decisions. 1. One-sentence definition of the concept in plain terms. 2. Why it matters: the problem it solves or the mistake it prevents. 3. How it works, at the level of detail the reader needs to act, and no deeper. 4. When to use it (and when not to). 5. A link to the how-to that applies it. A concept page should hand off to a task. **Reference page** is for a reader who already knows what they want and needs exact details. - Lead with the signature, syntax, or endpoint. - List every parameter with type, whether it's required, and the default. - Give one runnable example per entry. - No narrative. The reader is scanning, not reading. - Order options the way readers need them: the common case first, then selection and targeting, then advanced or CI-specific behavior. ## Improving an existing page When the input is a page that already exists, triage before you rewrite. 1. Name the page type and the one task or idea it serves. If it serves more than one, split it first. 2. Read it as the target reader and mark every place you'd get stuck: a missing prerequisite, a command with no context, an unexplained result, a claim you can't verify. 3. Fix in this order, because each unblocks the reader more than the next: 1. Missing prerequisites or setup that make later steps fail. 2. Steps with no context, wrong commands, or no way to confirm success. 3. Hidden limitations and claims you can't verify. 4. Slop and tone. 4. Change structure and wording freely. Don't change technical facts you can't confirm; flag them instead. ## Writing a step Every step follows the same rhythm. Don't skip parts of it. 1. **One sentence of context before any code.** Say what the step does and why. - Good: "Install the Prisma CLI so you can run migrations from your terminal." - Weak: "Run the following command." (Why? What does it do?) 2. **The exact command or code.** It must run as written. Label code blocks with the file path when the reader edits a file. 3. **What the reader should see.** Show real output, a created file, or a screen. Readers use this to confirm they're on track. 4. **A short explanation of the result**, only when it isn't obvious from the output. 5. **The likely failure and its fix**, when a step commonly breaks. One line: "If you see `EADDRINUSE`, another process is using the port; stop it or set `PORT`." This is what makes a doc feel hand-held instead of hopeful. ### Example: a weak step rewritten Weak: > **Initialize Prisma** > Run `npx prisma init`. Better: > **Initialize Prisma** > Set up Prisma in your project. This creates a `prisma/` directory with your schema file and a `.env` file for your database connection string. > > ```terminal > npx prisma init > ``` > > You now have `prisma/schema.prisma` and a `.env` file. Open `.env` and confirm `DATABASE_URL` is present. ## Concrete rules - Address the reader as "you". Use the imperative for actions: "Run", "Open", "Add". - Put the requirement or context before the command, never after. - Every code block must run or compile as written. No pseudo-code in step-by-step instructions. - Label code blocks with the target file path when the reader edits or creates a file. - Prefer one complete, real example over an abstract description of options. Show the common case; link to the reference for the rest. - State a limitation where the reader will hit it, inline with the relevant step, not in a footnote. - Link the first mention of a concept the reader may not know. Don't re-link it every time. - Use exact product names: Prisma Postgres, Prisma Compute, Prisma 8. Don't shorten "Prisma Postgres" to "the database" or "Prisma 8" to "the ORM" once a page covers more than one product. - When you tell the reader something is automatic, show the trigger that makes it happen and how to confirm it did. "Compute injects `DATABASE_URL` automatically" needs a follow-up: "Run `prisma compute env` to confirm it's set." ## Teach in plain language Open every concept with the plain-words version a newcomer can repeat, then a concrete everyday example, and only then the precise terms. Jargon may appear after the reader has the idea, never as the introduction to it. Weak (jargon-first): > Data modeling is the step where you describe the shape of your application's data: the entities it works with, the fields each entity carries, and how those entities connect. You author that description as a schema, and it compiles into a versioned contract that your code, migrations, and tooling all read from. Better (idea first, example second, terms last): > Data modeling is the process of describing the data your application needs and how that data is connected. > > For example, a blog has users, posts, and comments. A user has fields like an email and a name. These models also relate to each other: a user can write many posts, and a post can have many comments. > > In Prisma 8, you define this structure in a `contract.prisma` file. This file becomes the shared contract between your application code, database migrations, and developer tools. The same rule applies inside sections: when a paragraph packs several decisions together, split it into short subsections, one decision each, and show a code block for every option you name. Guidance that lives only in inline code (`Int @id @default(autoincrement())` mid-sentence) belongs in a fenced block with a sentence of its own. Never lean on internal vocabulary ("runtime family", "lowering", "execution stack") without a one-line plain definition at first use. For hands-on guides (anything that builds something), follow the house guide style used by /docs/guides/runtimes/bun and the middleware authoring guide: an Introduction stating what the reader builds, Prerequisites, short numbered step headings ("## 1. Create the middleware"), one action per step with the exact file path on every code block, the real expected output after the step that produces it, a likely-failure line where a step commonly breaks, and options or reference material only after the working result. ## Cut the slop Delete these on sight. They add length, not clarity. - **Throat-clearing openers**: "Here's the thing", "It turns out", "The truth is", "Let me walk you through". State the content directly. - **Meta-commentary**: "In this section, we'll…", "As we'll see…", "Now, let's…". Just write the section. - **Filler adverbs**: really, just, simply, actually, basically, of course. ("Simply run" insults a stuck reader.) - **Business jargon**: leverage, unlock, seamless, robust, powerful, deep dive, game-changer. Replace with the plain verb or cut. - **Machine vocabulary**: crucial, pivotal, key (as an adjective), enhance, foster, empower, showcase, underscore, highlight (as a verb), delve, landscape, ecosystem, tapestry, testament, vibrant, comprehensive, streamlined, cutting-edge, "Additionally," opening a sentence, utilize for use, authored for wrote. The full table with replacements is in `.claude/skills/docs-reader-review/references/ai-writing-signs.md`. - **Didactic openers**: "It's important to note that", "It's worth noting", "Keep in mind that". Cut the opener; the sentence stands alone. Use a `:::note` directive when the point must stand out. - **Section summaries**: "In summary", "In conclusion", "Overall", or a closing paragraph that restates the section. Stop when the last step is done. - **Vague value claims**: "a powerful experience", "the future of X", "everything you need". Replace with a specific capability or remove. - **Em dashes**. Use a comma, colon, or period instead. Straight quotes, not curly. - **Hype**: don't sell inside docs. The reader already chose the product; they want it to work. ## Don't write like a model Model-drafted docs share habits a reviewer can spot in one pass. None of these is wrong in isolation; their density is what gives a page a synthetic voice. Check for each before finishing. The list below is the docs-specific set; the longer catalogue, adapted from Wikipedia's [Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), is in `.claude/skills/docs-reader-review/references/ai-writing-signs.md`, and `.claude/skills/docs-reader-review/scripts/check-ai-signs.sh` catches the ones a regex can. The cause behind all of them: a model writes the most likely sentence, which is the one that could be true of anything. Specific facts get smoothed into generic praise. So the fix is never a synonym; the fix is the specific thing: the exact command, the number, what the reader sees. - **Copula avoidance**: "serves as", "acts as", "functions as", "stands as", "represents", "boasts", "offers" where "is" or "has" is the word. "Prisma Postgres is a managed database", not "serves as a managed database solution". - **Participle tails**: a fact followed by an "-ing" clause that editorializes about it: "..., ensuring your queries stay fast", "..., making it easy to scale", "..., allowing teams to move faster". Delete the tail. If the consequence is real, give it its own sentence with a concrete claim. - **Puffed significance**: a feature described by its importance ("plays a crucial role", "is essential for", "marks a shift") rather than its behavior. Say what it does. - **Vague connection**: "associated with", "in connection with", "related to", "tied to" in place of the actual relationship. Say what points at what. - **Vague attribution**: "many developers find", "it is widely considered", "best practice suggests". Name who, or state the recommendation as ours. - **Elegant variation**: the same thing called the client, then the library, then the ORM, then the runtime, to avoid repeating a word. In docs the reader cannot tell if those are one thing or four. Pick one name and repeat it. - **Bold-label lists everywhere**: `**Label:** description` bullets in place of paragraphs. Use them for items of the same kind the reader will scan; put reasoning in prose. Bold is otherwise for UI labels and the rare must-not-miss warning. - **Limitations formula**: "Despite its advantages, X faces several challenges... Despite these challenges, X remains a strong choice." State each limitation as a plain fact where the reader hits it, and stop. - **Title Case headings** and `---` breaks between sections. House style is sentence case, and headings already separate sections. - **Leaked chat**: "Here's an overview of", "I hope this helps", "Let me know if", unfilled `[placeholders]`, and "while specific details are not widely documented, X likely..." (the page either knows or marks a `Q` for the operator; it never guesses). - **Frontmatter echo**: the body's first sentence repeats the frontmatter `description` almost verbatim. The description summarizes the page for cards and search results; the opening orients the reader. Write them differently, and define the product once, not once per metadata field. - **Contrast slogans and negative parallelism**: "X, not Y", "not just X but also Y", "it isn't X, it's Y", "Y rather than X" ("injected, not discovered", "built for agents, not just terminals", "refuses to guess"). Each frames a misconception the reader did not have and then resolves it. One per page at most, and only where the reader would genuinely have assumed X. State the behavior plainly instead. - **Absolute stacking**: "never", "every", "nothing", "always", "cannot drift" piling up across a page. Each absolute is a promise the product has to keep. Keep the ones you can verify and that the reader needs; describe what happens rather than asserting what can't. - **Exception-packed sentences**: one sentence carrying the normal case, an exception, its reason, the alternative, and a safety condition, held together by semicolons. One idea per sentence: state the default first ("By default, the command uses…"), then the exception as its own sentence ("In CI or other headless environments, set…"). A semicolon joining distinct ideas is usually two sentences. - **Staccato**: the opposite failure, and the usual result of over-correcting the one above. A run of short, clipped sentences, each holding one fact, with no connective between them: "The field takes no `@default`. Omit `id` when you create a document and MongoDB assigns it." or "A profile needs a user. A user does not need a profile. So `Profile` holds `userId`." Every sentence lands with the same thud and the reader has to work out how the facts relate. One idea per sentence does not mean one clause per sentence. When two facts are cause and effect, contrast, or condition and result, join them with "because", "so", "but", "while", or a colon, and let one sentence carry both: "A profile needs a user, but a user does not need a profile, so `Profile` holds `userId`." Vary sentence length within a paragraph, and read it aloud before finishing: if three sentences in a row are under ten words, at least two of them probably belong together. - **Manager-voice openers**: "`service` manages services…", "handles", "manages everything around". Lead with the user action or outcome ("Use `service` commands to manage…") and use concrete verbs: creates, stores, uses, selects, targets, deploys, builds. - **Coined shorthand**: compressed phrases invented mid-page ("local pin", "pick a target") instead of saying what actually happens. Spell out the relationship, and keep one consistent user-facing vocabulary: service, project, configuration, deployment, credentials. - **Implementation language**: internal detail that doesn't help the reader act ("the root node is `<entry>`'s default export"). Translate it into the behavior they observe ("the application exported as the default export from `<entry>`"). - **Buried caveats**: a warning folded into a trailing clause. Turn it into a direct instruction: "The deploy command does not build your application. Run your build command before deploying." - **Confusable state left implicit**: when two things could be mixed up (local state vs committed configuration), contrast them directly: what is local, what is committed, and what each is used for. - **Mid-clause links**: a link dropped between unrelated clauses. Introduce it after the context it supports: "See [Deploying](…) for details." - **Definition cascade**: a landing page that defines every noun in identical rhythm ("An application is… A service is… A branch is…"). Define a term where the reader first needs it. If a glossary earns its place, keep it short and hand off to a page that goes deeper. - **Prose restating code**: after a code block, narrating what each line does. Explain only what the code can't show: why, or a non-obvious consequence. - **Triad reflex**: three-part lists everywhere ("reviewable, repeatable, and versioned"), three adjectives, three examples, three bullets. Models reach for three by reflex. Use the number of items there actually are; cut members that don't earn their place. - **Exhaustive nav dumps**: a "What to read next" that lists every sibling page in the same grammatical form. Pick the two or three pages this reader most likely needs next; the sidebar already lists everything. What is not a sign, and not a reason to rewrite: correct grammar, precise vocabulary in general (the signal is the specific words above, not formality), a single "However" or "so", or short well-organized paragraphs. Plain "is", "has", "wrote", "used", and hedges like "usually" or "perhaps" are how people write; keep them. The same applies to PR descriptions for docs changes: write a short reviewer-facing summary of what changed and why, and put validation details (commands run, environments used) in a collapsed section. Don't paste the working session's log. ## Voice - Calm and direct. The reader is mid-task, not browsing a landing page. - Accuracy over persuasion. If behavior is uncertain or version-dependent, say so and say how to check. - Name limitations honestly and early. Hiding them costs the reader more later. ## Final pass Before you finish, check: - [ ] Could a reader with only the listed prerequisites complete every step? - [ ] Does every command run as written, with no missing setup? - [ ] Does each step say what it does before showing the command? - [ ] Is there a way to verify success at the end? - [ ] Did you cut every phrase from "Cut the slop"? - [ ] Did you check the page against every pattern in "Don't write like a model"? - [ ] Did you read the prose aloud and rejoin any run of clipped sentences that belong together? `.claude/skills/docs-reader-review/scripts/check-staccato.py <page>` finds the worst runs. - [ ] Does `.claude/skills/docs-reader-review/scripts/check-ai-signs.sh <page>` come back clean? - [ ] Are product names and limitations accurate? - [ ] Has the page been through `docs-reader-review`? A fact review checks truth; the reader review checks whether a reader without your context can follow it. Nothing is finished until that pass reports no sentence the reader could not restate.