repo-docs

Repo docs

User-facing repo docs serve a stranger: someone who arrived cold, is deciding whether the project fits, and then sets it up or uses it. Their coding agent often reads the same page and follows its steps. Write every page for that pair, never for the owner.

The guidance has two layers. The content rules apply to every user-facing doc in every repo. The format defaults apply only where the repo, its ecosystem, or its docs site has no convention of its own; when one exists, follow it.

Most rules below are judgments, each with the test that decides it. Apply the test to the case in front of you: the same detail can belong in a reference table and not in a heading, or in a closing section and not in a setup step. Scale the steps to the change as well: a one-line fix needs the facts it touches and their echoes, while a new doc or a public-release pass needs every step in full.

RFCs use the document-mode guidance for their sections. PR descriptions and commit messages use the sentence and verification rules, with their repository's format rather than a documentation mode. Product UI strings use the product's copy guidelines.

Steps

1. Gather the facts

Read the doc you are changing, its siblings, the code and config behind each claim, and every echo of its facts elsewhere (website copy, storefront text, in-app help, installed docs, other docs in the repo). Check the repo's visibility with gh repo view --json visibility and look for existing conventions: a docs site, a style the other docs share, README requirements from the plugin or package directory the project ships through.

Done when you can name the audience, the conventions that bind the doc, every echo location, and the code path behind each claim you will touch.

2. Place the material

Put each piece of material in the document that owns it, using the map below. Give each fact one canonical home and link to it from everywhere else; copy a fact only where a link cannot reach (a storefront, an app's help text).