Deep Research Read Me
Shape a GitHub OSS README so readers quickly understand what the project does and how to start using it.
Workflow
Confirm the context.
- Identify the project type: library, CLI, web app, or GitHub Action.
- Identify the target reader: user, evaluator, or contributor.
- Identify the README goal: create, improve, or review.
Build the first view.
- Put the project name in the H1.
- State the value in one or two sentences before explaining the technology stack.
- Provide the shortest path to Quickstart.
- Include only essential links, such as Docs, Issues, and Releases.
Make Quickstart short.
- Keep it to roughly three to six lines in this order:
Requirements,Install,Run. - Keep only commands that can actually be run.
- Move long OS-specific setup paths to
docs/installation.md.
- Keep it to roughly three to six lines in this order:
Finish the structure.
- Use these sections as the default shape:
HighlightsQuickstartUsageDocumentationGetting helpContributingLicense
- Move detailed explanations to
docs/and keep only relative links in the README.
- Use these sections as the default shape:
Run the final review.
- Confirm a reader can get from discovery to first successful run within five minutes.
- Check for broken links, version assumptions, and stale instructions.
- Use
references/readme-review-checklist.mdfor coverage.
Output Template
When drafting README content, prefer the template in references/readme-template.md.
Review Policy
When reviewing an existing README, prioritize findings in this order.
Critical
- Quickstart cannot be executed.
- Required information is missing: What, How to start, or Help.
- The README is so large that the start path is buried.
Warning
- Section order does not match the reader's decision flow.
- Links to docs are weak or hard to find.
- Too many badges or links obscure the project's value.
Info
- Wording can be simpler.
- Examples would help, such as CLI examples or minimal code examples.
- FAQ or troubleshooting links would help.
Reference Files
- Practical checklist:
references/readme-review-checklist.md - README template:
references/readme-template.md