Core content
- Explain what the project does and who it is for in the opening screen.
- Provide supported environments, install commands, and the shortest working example.
- Document required environment variables with safe examples and secret-handling notes.
- Cover key capabilities, common failures, and where to get help.
- Verify test, lint, and build commands, contribution steps, license, and contact links.
Formatting review
- Keep heading levels sequential and make sure internal links point to real sections.
- Add image descriptions and language labels to fenced code where useful.
- Run copied commands in a clean environment and remove stale badges or links.
Run the copied steps in a clean environment
A configured development machine hides missing setup. Follow the README from installation in a fresh folder or CI job and look for undeclared global tools, environment variables, and authenticated sessions.
Do not make the README carry every record
Move release history, long incident analysis, and detailed API contracts to focused documents. Keep a short link that tells the reader when to use them, so onboarding and operational history do not compete on one page.
Template and checks
Load the README template, then use Document check for headings, links, images, and code fences.