How to Write a Good README.md — The Complete Guide

Your README is the single most important file in your repository. It's the first thing potential users, contributors, and employers see. A great README turns visitors into users. A bad one — or no README at all — sends them elsewhere.

The essential sections (in order)

1. Project title and description

One line that explains what your project does. Not how it works, not what technologies it uses — what problem it solves.

Bad: “A Next.js application built with TypeScript, Tailwind CSS, and Supabase.”

Good: “Generate professional README files for any GitHub repository in seconds.”

2. Badges

Build status, version, licence, test coverage. Badges signal that the project is maintained and professional. Check our badges guide for details.

3. Screenshot or demo

A screenshot or GIF is worth a thousand words of documentation. Show the tool in action. If it's a CLI, show terminal output. If it's a web app, show the UI.

4. Quick start

Get the user from zero to running in the fewest steps possible. This should be copy-pasteable:

• Installation command
• Minimum configuration
• First run command

If your quick start is more than 5 steps, your setup is too complex. Simplify the defaults or provide a Docker option.

5. Usage examples

Show the most common use cases with actual code. Not contrived examples — real scenarios that real users will encounter. Include expected output where helpful.

6. API reference or configuration

For libraries: document every public function, its parameters, and return values. For tools: list every configuration option with defaults. Tables work well here.

7. Contributing

If you want contributions, make it easy. Link to a CONTRIBUTING.md with setup instructions, coding standards, and PR process. If you don't want contributions, say so — it saves everyone time.

8. Licence

State the licence clearly. Link to the full LICENCE file. If people can't quickly confirm they can use your code, they won't.

Common mistakes

• Tech stack as description — Nobody cares that you used React. They care what the tool does for them.
• No installation instructions — “Clone the repo and run it” is not enough. What dependencies? What Node version? What environment variables?
• Outdated examples — Nothing kills trust faster than code examples that don't work. Test your README examples as part of your CI.
• Wall of text — Use headings, code blocks, and lists. Developers scan, they don't read paragraphs.

What top repos get right

Look at repos with 10k+ stars. They almost always have:

• A one-line description that sells the benefit
• A hero image or demo GIF
• A “try it now” that takes under 30 seconds
• Comprehensive but scannable documentation
• Active badges showing the project is alive