---
name: docs-files-api
description: Where docs go — README vs CONTRIBUTING vs AGENTS.md, and JSDoc placement — use when writing or reviewing a README, CONTRIBUTING, or AGENTS.md/CLAUDE.md; when someone asks "how do I run it?" and there's no README; when writing or reviewing code comments, JSDoc, or file headers; deciding where @file/@see links go; documenting exported symbols or external specs; when a `//` comment explains what a declaration is or does (it belongs in JSDoc).
---

# Documentation Conventions

## README, CONTRIBUTING, AGENTS.md

A **README** does two jobs, in this order:

- **Marketing:** why should the reader care? What's cool about this?
  A few lines, not a feature matrix.
- **Getting started:** get them to TADA! with no fuss. Readers skip to
  the first fenced block and copy it; if it doesn't work, boo. So that
  block runs as-is from a fresh clone and ends with something to look
  at (a URL, output). No architecture, no principles.

Everything else goes in **CONTRIBUTING**: design, layout of the code,
how to test, conventions, deploying.

**AGENTS.md is a symlink to CONTRIBUTING.md** (likewise CLAUDE.md, if a
tool wants one). Good advice is good advice, for people and bots alike.
If agents need something people don't, give it a short section in
CONTRIBUTING.

## JSDoc

JSDoc placement rules (from the
[portfolio-contract contributing notes](https://github.com/Agoric/agoric-sdk/blob/master/packages/portfolio-contract/CONTRIBUTING.md#documentation-conventions)):

- **File comments:** Use a 1–2 line `@file` summary rather than a long file
  header essay. Include `@see` links only for major entry points, and keep
  those links intra-file (e.g. `{@link someExport}`), not external URLs.
- **Entry-point JSDoc:** Put the meaningful docs on the *exported* symbols —
  that's what shows up in IDE call sites. External URLs belong here when they
  define the canonical ABI/spec of the thing being exported.
- **API docs are JSDoc, not `//`:** What a function, class, method,
  type, field, or constant *is* or *does* goes in a `/** … */` comment on
  its declaration — IDEs show it at call sites and on hover; a `//` line
  above the declaration shows nowhere. `//` is for implementation notes
  inside a body: the *why* of a non-obvious line, next to that line.
- **Exception: program scripts** (run directly: a shebang, or
  `import.meta.main`). The manual goes at the top: a one-line purpose, a
  usage synopsis, the arguments, and what it writes or prints. People
  open a script to learn how to run it, and its `main` has no call sites
  for JSDoc to show at. If the script prints its usage, make the manual a
  `HELP` string constant right under a one-line `@file` (JavaScript has
  no docstrings; a string literal is the honest equivalent) rather than
  copying it or reading the script's own source. Helpers inside still get
  their own JSDoc.
- **Write for the reader, not the conversation:** Comments say what the
  code is and why, in the reader's terms. No traces of how it came to be
  (design discussions, who asked, "for now", analogies used while
  deciding), and nothing the code or its shebang already says.
- **External design constraints:** If a module is constrained by external
  contracts, standards, or off-repo design docs, add a short JSDoc note with a
  `@see` link to the authoritative source at the relevant entry point(s).

In short: brief at the top of the file, meaty on exports (in JSDoc),
`//` only for the why inside bodies, `@see` to authoritative external
sources only where they define the contract.