j5ik2o-deep-research-read-me

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.
Finish the structure.
- Use these sections as the default shape:
  - Highlights
  - Quickstart
  - Usage
  - Documentation
  - Getting help
  - Contributing
  - License
- Move detailed explanations to docs/ and keep only relative links in the README.
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.md for coverage.

When drafting README content, prefer the template in references/readme-template.md.

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.