From cc10a3a77d81007a01ea393900f3d37a5ee4059f Mon Sep 17 00:00:00 2001 From: adidavid014 Date: Tue, 30 Jun 2026 10:19:37 -0400 Subject: [PATCH] docs: add prose-update reference to fern-docs skill Co-Authored-By: Claude --- skills/fern-docs/SKILL.md | 1 + skills/fern-docs/references/prose-updates.md | 70 ++++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 skills/fern-docs/references/prose-updates.md diff --git a/skills/fern-docs/SKILL.md b/skills/fern-docs/SKILL.md index 5bd4fae..5c8ddff 100644 --- a/skills/fern-docs/SKILL.md +++ b/skills/fern-docs/SKILL.md @@ -32,6 +32,7 @@ Fern's configuration evolves. Look things up rather than guessing. | Task | Read | |------|------| +| Updating prose/guide pages after an API definition or spec change | `references/prose-updates.md` | | Writing or editing a changelog entry | `references/changelog.md` | | Setting up a product switcher, adding a product, or refactoring nav into products | `references/products.md` | | Moving, renaming, or deleting a page, or any edit that changes a published URL | `references/redirects.md` | diff --git a/skills/fern-docs/references/prose-updates.md b/skills/fern-docs/references/prose-updates.md new file mode 100644 index 0000000..1c7d9ae --- /dev/null +++ b/skills/fern-docs/references/prose-updates.md @@ -0,0 +1,70 @@ +# Prose updates from an API change + +When an API definition changes, the auto-generated API reference updates itself — +but the prose around it can go stale. This reference covers how to update +**prose/guide/narrative pages** so they still match the API. Read it whenever a +diff to an API spec (OpenAPI, Fern Definition, or the generated SDK) prompts a +docs change. + +## Don't touch the generated API reference + +Fern regenerates the API reference from the spec on every build — endpoint pages, +parameter tables, schemas, and request/response examples. Editing those by hand +is wasted work: the change is either overwritten on the next build or, worse, +drifts from the source of truth. + +- **Only edit prose** — guides, tutorials, quickstarts, conceptual pages, + overviews, and hand-written narrative. These are the `.mdx` files you actually + authored, not the ones Fern emits from the API definition. +- If the reference itself is wrong, fix the **API definition**, not the generated + page. That's outside this skill — flag it rather than patching the rendered output. + +## Find the prose the change made stale + +A spec diff rarely touches every page. Identify the prose that now contradicts the +API before editing anything. + +- Pull the concrete identifiers out of the diff: endpoint paths, method names, + field and parameter names, enum values, auth scheme. Grep the prose for each: + + ```bash + grep -rln "\|\|" fern --include="*.mdx" + ``` + +- Read each hit and decide whether the change actually invalidates it — a renamed + field in a code sample, a removed parameter described in a step, a changed + default mentioned in passing. Skip pages that merely link to the reference; the + reference updates itself. +- **Prefer editing existing pages over creating new ones.** A changed API usually + means an existing guide is now slightly wrong, not that a new guide is needed. + Search for the page that already covers the workflow and fix it in place. +- **Make minimal, targeted edits.** Change the sentence, sample, or step the diff + invalidated — don't rewrite a page that's still mostly correct. + +## Additive-only changes often need no prose edits + +When the change is purely additive — a new optional field, a new endpoint, a new +enum value — and nothing in the existing prose now reads as wrong, it's fine to +make **no prose edits at all**. The generated reference already reflects the +addition. Don't invent a guide for every new endpoint; add prose only when a +reader following the existing docs would otherwise be misled or stuck. + +## Cross-reference the pages you touch + +A prose edit that introduces or changes a concept usually leaves related pages +pointing at stale behavior or failing to mention the new one. Apply the +**Cross-referencing** rules in `SKILL.md`: one canonical home, grep for the +feature and related keywords, use the lightest link form that works, and phrase +links on a noun already in the sentence. + +Internal links are URL paths from this repo's `docs.yml` and page frontmatter — +**not** file paths or relative paths on disk. Build every link per the **Links** +section of `SKILL.md`; never derive a URL from the directory layout. + +## What not to do + +- Don't hand-edit generated API reference pages — Fern overwrites them. +- Don't create a new page when an existing one can be corrected. +- Don't rewrite a page when a targeted edit fixes the staleness. +- Don't manufacture prose for a purely additive change the reference already covers. +- Don't write links from file paths — resolve them from `docs.yml` per `SKILL.md`.