How to Write a README That Gets Stars on GitHub

Your README is the front door of your GitHub project. Studies show that repositories with well-structured READMEs get 3-5x more stars and contributors than those with minimal documentation. Yet most developers treat it as an afterthought.

This guide shows you exactly what makes a README stand out, with practical tips from the most starred repositories on GitHub.

The 30-Second Rule

Visitors to your repository make a stay-or-leave decision in about 30 seconds. In that time, they need to understand:

1. What does this project do?
2. Why should I care?
3. How do I use it?

If your README doesn't answer these three questions above the fold, you're losing potential users before they ever try your project.

The Essential Sections

1. Title + Description + Badges

Start with a clear title, a one-line description, and shields.io badges for build status, license, and version:

# My Project

![Build](https://img.shields.io/github/actions/workflow/status/user/repo/ci.yml)
![License](https://img.shields.io/github/license/user/repo)
![npm](https://img.shields.io/npm/v/my-package)

A fast, lightweight tool that does X for Y developers.

Badges provide instant credibility — they show your project is actively maintained and properly licensed.

2. Quick Start (The Most Important Section)

Get users from zero to running in under 60 seconds. Show the minimal installation and usage:

## Quick Start

npm install my-tool

// In your code:
import { analyze } from 'my-tool';
const result = analyze('Hello world');
console.log(result); // { words: 2, chars: 11 }

If someone can't get your tool working within a minute of reading your README, they'll move on to an alternative.

3. Features List

Use a bullet list with brief descriptions. Include what makes your project different from alternatives:

## Features

- **Fast** — 10x faster than similar tools (benchmarks below)
- **Zero dependencies** — No bloated node_modules
- **TypeScript native** — Full type definitions included
- **Tree-shakeable** — Only bundle what you use

4. Installation

Show every supported package manager. Developers are picky about this:

## Installation

# npm
npm install my-tool

# yarn
yarn add my-tool

# pnpm
pnpm add my-tool

5. Usage Examples

Show 2-3 real-world examples, not just the trivial "hello world" case. Include comments explaining what each part does.

6. API Reference

For libraries, document every public function with parameters, return types, and examples. Tables work well here:

| Method | Parameters | Returns | Description |
|--------|-----------|---------|-------------|
| `analyze(text)` | `string` | `Result` | Analyze text |
| `compare(a, b)` | `string, string` | `Diff[]` | Compare texts |

7. Contributing

Even a simple "PRs welcome" section increases contributions. Better yet, link to a CONTRIBUTING.md with setup instructions for development.

Pro Tips from Top Repos

• Add a GIF or screenshot. Visual projects (UI libraries, CLI tools) get significantly more engagement with a demo GIF at the top.
• Include a Table of Contents. For README files longer than 3 screens, a TOC helps users navigate.
• Show, don't tell. Instead of saying "easy to use," demonstrate it with a 3-line code example.
• Keep it updated. A README that references v1.0 when you're on v3.2 screams "abandoned project."
• Add "Why" context. Explain the problem your project solves. "I built this because X was too slow/complex/expensive."
• License badge. Always include a license. No license = no one can legally use your code.

README Anti-Patterns

• "TODO: Add documentation" — Never push this to main. Write at least a basic README before going public.
• Wall of text — Use headings, code blocks, and bullet points. Nobody reads paragraphs in a README.
• Auto-generated only — Tool-generated READMEs (from `npm init` etc.) are a starting point, not the final product.
• No examples — The #1 complaint about open-source projects is "I don't know how to use it."

The best README is one that makes the reader think: "I could get this working in 5 minutes." — Every successful open-source maintainer

Checklist Before Publishing

1. Title clearly states what the project does
2. One-paragraph description answers "what" and "why"
3. Badges show build status, license, and version
4. Quick start gets users running in under 60 seconds
5. At least 2 real-world usage examples with code
6. Installation instructions for all major package managers
7. Contributing section (even if brief)
8. License clearly stated
9. No broken links or outdated information
10. Spell-checked and proofread