Skip to main content

Documentation ownership

Give each public and maintainer document one clear responsibility.

Keep one source of truth for each instruction. Link to it from other documents. Do not maintain parallel release procedures.

Root README

Use this order for every public root README:

  1. Centered 128 px product icon.
  2. Centered product name.
  3. Centered one-sentence value proposition.
  4. npm, CI, and MIT badges.
  5. Release-status warning when the package is not stable.
  6. Why use the product.
  7. When to use it, including when not to use it.
  8. Requirements.
  9. Installation.
  10. The smallest useful example.
  11. Product concepts and benefits.
  12. Packages for a multi-package repository.
  13. Documentation.
  14. Contributing and development.
  15. Support and security.
  16. License.

A package README uses a compact form with purpose, installation, example, exports or requirements, documentation, support, security, and license.

Public documentation

Public pages explain supported behavior. Do not include internal proof paths, fixture names, release approval steps, or absolute paths from a maintainer's computer.

Use Lupinum Controlled English as defined in docs/WRITING.md. State that it is based on ASD-STE100. Do not claim formal certification.

Maintainer documentation

Put operational steps in MAINTAINING.md. Put durable technical decisions in architecture decision records only when the decision needs history and tradeoff context. Do not create an ADR for ordinary maintenance.

Technical READMEs

Keep fixture, font-license, benchmark, proof, migration, and ADR-index READMEs technical and unbranded. Their purpose is local explanation, not marketing.