DEV Community

Gingiris
Gingiris

Posted on • Originally published at github.com

GitHub README Best Practices: How to Write a README That Gets Stars

#github #opensource #readme #documentation

Quick Answer: A great GitHub README needs a clear title, concise description, visual demo (GIF/screenshot), quick start guide, and a compelling "why" section. This guide shares README best practices from projects with 60k+ stars.

Why Your README Matters

Your README is your project's landing page. It's often the difference between someone starring your repo or bouncing in 3 seconds.

I'm Iris, former cofounder & COO of AFFiNE (60k+ GitHub stars). After helping grow multiple open source projects, I've learned that README quality directly correlates with star growth.

Project Stars README Quality
AFFiNE 60k+ Optimized
Average OSS <100 Minimal

GitHub README Best Practices

1. Start With a Clear Value Proposition

The first 2 lines should answer: What is this? Why should I care?

# ProjectName

> One-line description of what it does and why it matters
Enter fullscreen mode Exit fullscreen mode

❌ Bad: "A tool for developers"
✅ Good: "Open-source Notion alternative with real-time collaboration — 60k+ stars"

2. Add Visual Proof Immediately

After the title, show don't tell:

  • GIF demo (15-30 seconds max)
  • Screenshot of the main interface
  • Architecture diagram for technical projects 
<div align="center">
  <img src="demo.gif" alt="Product Demo" width="600" />
</div>
Enter fullscreen mode Exit fullscreen mode

3. Badges That Matter

Only include badges that build trust:

Badge Type Why Include
Stars Social proof
License Legal clarity
Build status Quality signal
Last commit Active maintenance

Skip: Download counts, coverage %, and vanity metrics.

4. Quick Start in 30 Seconds

Users want to try before they commit. Make it copy-paste simple:

## Quick Start
Enter fullscreen mode Exit fullscreen mode


bash
npm install your-package
your-package init


That's it! Open http://localhost:3000 to see it running.
Enter fullscreen mode Exit fullscreen mode


markdown

5. Feature List as a Table

Tables are scannable. Bullet lists are not.

## Features

| Feature | Description |
|:--------|:------------|
| Real-time sync | Collaborate with your team instantly |
| Offline mode | Works without internet |
| Self-hosted | Your data, your servers |
Enter fullscreen mode Exit fullscreen mode

6. The "Why" Section

Explain the problem you're solving. This builds emotional connection:

## Why ProjectName?

Existing tools are either:
- Too expensive for indie developers
- Too complex for simple use cases
- Not open source

We built ProjectName because [personal story].
Enter fullscreen mode Exit fullscreen mode

7. Clear Documentation Links

Don't dump everything in the README. Link out:

## Documentation

- [Getting Started](docs/getting-started.md)
- [API Reference](docs/api.md)
- [Contributing](CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)
Enter fullscreen mode Exit fullscreen mode

8. Contribution Invitation

Make it welcoming:

## Contributing

We love contributions! See our [Contributing Guide](CONTRIBUTING.md) to get started.

Not sure where to start? Check issues labeled `good first issue`.
Enter fullscreen mode Exit fullscreen mode

README Template

Here's a battle-tested template:

<div align="center">
  <img src="logo.png" width="120" />
  <h1>Project Name</h1>
  <p>One-line value proposition</p>

  <!-- Badges -->
  [![Stars](badge)](link)
  [![License](badge)](link)
</div>

<div align="center">
  <img src="demo.gif" width="600" />
</div>

## Quick Start
[30-second setup]

## Features
[Table format]

## Why This Project?
[Problem + Story]

## Documentation
[Links]

## Contributing
[Invitation]

## License
[MIT/Apache/etc]
Enter fullscreen mode Exit fullscreen mode

FAQ: GitHub README

How long should a README be?

500-1500 words is the sweet spot. Long enough to be comprehensive, short enough to be read. Use documentation links for details.

Should I include installation for every platform?

No. Include the most common method (usually npm/pip/brew), then link to detailed installation docs.

What's the best format for images?

  • GIFs for demos (< 5MB)
  • PNGs for screenshots
  • SVGs for diagrams and logos

Host images in the repo's /assets folder or use a CDN.

Should I translate my README?

For global reach, yes. Use language links at the top:

**[English](README.md) | [中文](README-zh.md) | [日本語](README-ja.md)**
Enter fullscreen mode Exit fullscreen mode

Common README Mistakes

Mistake Fix
Wall of text Use headers, tables, and whitespace
No visuals Add GIF demo or screenshot
Complex setup Simplify to 2-3 commands
Missing "why" Add motivation section
Outdated info Set up CI to check links
No contribution guide Add CONTRIBUTING.md

README Checklist 

□ Clear one-line description
□ Visual demo (GIF/screenshot)
□ Essential badges only
□ Quick start (< 30 seconds)
□ Features table
□ "Why" section with story
□ Documentation links
□ Contributing invitation
□ License
Enter fullscreen mode Exit fullscreen mode

Real Examples

Projects with excellent READMEs:

Project Stars Why It Works
AFFiNE 60k+ Clear value prop, visual demo, feature table
Supabase 70k+ Instant demo, comparison table
Excalidraw 80k+ Interactive demo link, minimal text

Summary

Your README is your project's first impression. Invest time in:

  1. Clear value proposition — What and why in 2 lines
  2. Visual proof — GIF or screenshot immediately
  3. 30-second quick start — Copy-paste simple
  4. Scannable structure — Tables over bullet lists
  5. Emotional connection — Tell your "why"

A great README doesn't just document — it sells.

Free Resources

Questions? Drop a comment or reach out on Twitter @WeiYipei.

This guide is part of the Gingiris Open Source Playbook — battle-tested strategies from 60k+ GitHub stars.

Top comments (0)