Public README Polisher
Polish the README as the repo's public front door: credible, scannable, actionable, and claim-safe.
Use When
- a README feels plain
- a repo needs a public first impression
- a docs landing page needs clearer value, install path, or proof
- a visual asset could make the repo easier to understand
Process
- Audit repo truth: purpose, install path, tests, license, security, CI, docs, examples, and public claim boundaries.
- Define the public promise in one paragraph: who it helps, what it gives them, and what it does not guarantee.
- Improve the first viewport: title, optional hero, badges, concise opening, quick action, and a scannable "what you get" table.
- Add scanning structure: quick start, workflow diagram when useful, proof or sources near the claim, and links to deeper docs.
- Validate links, images, alt text, docs scan, tests, and the scorecard below.
Visual Asset Rules
- Use one purposeful hero only when it clarifies the repo.
- For generated images: no embedded text, no logos, no watermarks.
- Inspect the image before committing; reject generated image with readable fake text, broken UI, mascot drift, or misleading claims.
- Save README assets under
assets/readme. - Add alt text that explains the image function.
Claim Safety
- Cite official sources for factual pricing, cache, legal, API, or security claims.
- Say "patterns that worked for us" for experience-based recommendations.
- Avoid guaranteed savings, official endorsement, universal safety claims, or "works for every workflow" language.
- Keep related tools optional unless the repo truly depends on them.
Scorecard
Score each category 0-2. Pass at 13/16 or higher.
| Category | 2 means |
|---|---|
| First-viewport signal | repo purpose, visual tone, badges, and install path are clear without scrolling |
| Audience/value clarity | reader knows who it is for and what problem it solves |
| Scannability | tables, bullets, headings, and diagrams make scanning easy |
| Actionability | quick start and next links are concrete and current |
| Trust/proof | sources, CI, license, tests, and safety boundaries support the claims |
| Visual polish | assets feel intentional, domain-fit, and not generic stock decoration |
| Accessibility/asset hygiene | alt text, local paths, file size, and image rendering are sane |
| Claim safety | claims are bounded, sourced where needed, and public-safe |
Automatic blockers: private paths, secrets, broken local links, missing install path, false or guaranteed claims, generated image with readable fake text, missing alt text, failing docs scan.
Common Mistakes
- Making a marketing page that hides the actual install/use path.
- Adding a pretty image that does not explain the repo.
- Moving official citations away from the claims they support.
- Replacing precise safety boundaries with vague hype.
- Claiming completion without running the scorecard.
