How to Write a Good README for Your First Open-Source Project

The problem

A GitHub repo’s README is usually the only thing a stranger reads before deciding whether to use your project at all. One that’s just a project name and a wall of code, with no clear install step or working example, loses most of that audience before they ever try it.

Expected outcome

By the end of this guide you will have a README structure covering exactly what a first-time visitor actually needs, in the order they need it.

Requirements and costs

• Any text editor.
• Cost: free.

Step-by-step implementation

1. Download the template from the link below and save it as README.md at the root of your repo.
2. Write the one-sentence description first, before anything else — if you can’t describe what it does in one sentence, that’s worth resolving before writing the rest.
3. Put a copy-pasteable install command under Installation — test it yourself in a fresh folder before publishing, not just from memory.
4. Put the smallest real example that actually runs under Usage — not a snippet that looks plausible but was never actually executed.
5. Delete sections that don’t apply. A README with an empty “Configuration” header is worse than no header at all.

A real example

“Why use this instead of [the obvious alternative]?” is the section most READMEs skip, and it’s often the most useful one to a visitor comparing options — even a short, honest “it doesn’t do X, but it’s simpler to set up for Y” tells a reader more in one sentence than the rest of the README combined.

Verification and troubleshooting

What we actually checked: the template’s three load-bearing sections (Installation, Usage, License) are present and correctly structured. This is a structural check of the template file, not a review of any specific real project’s README.

Troubleshooting:

• You’re not sure what to put under “Usage.” Copy the exact commands you yourself would run to try the project for the first time, right now, on a machine that has nothing installed yet.
• You don’t have a CONTRIBUTING.md yet. Replace that section with a sentence or two on how someone would get started contributing — even an informal answer beats a dead link.
• The License section says MIT but there’s no LICENSE file. Add the actual file — a README claiming a license with no corresponding file is confusing at best and legally meaningless at worst.

Free vs. paid

This is free and complete as a Markdown template. There’s no meaningful paid alternative to a well-written README — this is purely a writing and structure problem, not a tooling one.

Free resources

The download is the full template.

Download the README template (ZIP, 1 KB)

Is there a paid version?

Not yet. This is the complete method. TNT Review has sold nothing to date and has no checkout, so any price we discuss in future should be read as a hypothesis, not an offer.