A README That Sells a Side Project

Visitors to a project judge it in seconds. They open the page, glance at the top and decide: stay or leave. For a code repository, a folder of files or a shared project, the thing they see first is usually the README.

A good README is the shop window of a side project. It says what is inside, shows it working and tells you how to come in. A poor one hides a good project behind a wall of text, or says nothing at all. This guide sets out what to put in a README, in what order and how to keep it honest.

What a README is for

Platform documentation describes it simply: a README tells other people why your project is useful, what they can do with it and how they can use it. A README is often the first item a visitor sees, and it usually covers what the project does, why it is useful, how to get started, where to get help and who maintains it.

That list is a good skeleton. But it is also useful to think about the reader. A README has several audiences.

• The curious passer-by, who wants to know in ten seconds whether this is for them.
• The new user, who wants to get it running.
• The contributor, who wants to help.
• Future you, who has forgotten how it works.

Design the top for the first, the middle for the second and the end for the third. The fourth benefits from all of it.

The top: win the first ten seconds

The top of the README should answer, immediately, three questions: what is this, is it for me, can I see it working?

A clear name. The same as everywhere else.

A one-sentence description. Plain words. "A command-line tool that turns a folder of recipes into a shopping list."

Proof it works. A screenshot, a short clip or a small example of input and output. A picture of the project doing its job is worth a page of description. Describe the image in alt text for readers who cannot see it.

A way to try it. A link to a live demo, if there is one, or a one-line command.

Badges, sparingly. A couple that carry real information, such as the licence or the build status, are fine. A wall of badges is noise.

Put nothing before these. A history of why you started the project belongs lower down.

What it is, and what it is not

A short paragraph after the opening can set expectations.

• What problem it solves.
• Who it is for.
• What it deliberately does not do.
• What state it is in: experimental, usable, stable.

Being honest here saves you from mismatched users and from support questions. "This is a hobby project. It works for the case in the example. It does not handle files over a certain size yet" is a perfectly good paragraph.

Getting started

This is the section most newcomers use. Make it work.

• Requirements. What they need installed first.
• Install. The shortest path: copy-paste commands where possible.
• First use. A minimal example that produces a visible result.
• Expected output. Show what success looks like.

Write each step as an action. Number them. Test them from scratch, on a clean machine or a fresh folder, because the steps you have run a hundred times hide assumptions.

A common failure is a README that was written once, early, and no longer matches the project. Run your own instructions every few releases.

Usage and examples

After the first success, show a few common uses.

• Two or three examples, from simple to useful.
• Short code blocks with comments.
• A link to fuller documentation for the rest.

Keep examples realistic. Real-looking data is more convincing and easier to follow than "foo" and "bar".

Configuration and options

If there are settings, list the important ones in a small table or list with their defaults. Link out for the full reference. Avoid copying everything into the README. It will go stale.

Help and community

Tell people where to ask questions and report problems.

• A link to the issue tracker or an email address.
• What information to include in a report.
• How quickly you usually reply, honestly.
• Whether you are open to contributions, and where to find guidelines.

Setting expectations protects you. "I maintain this in my spare time and reply within a week or two" is kind to yourself and to users.

Contributing

If you welcome help, say how: how to set up a development copy, how to run tests, what kind of changes you want and how to submit them. If you do not accept contributions, say that too. A short, clear paragraph prevents hurt feelings.

Many projects add separate files for contribution guidelines and a code of conduct. The platform documentation notes that a README, along with a licence, citation file, contribution guidelines and a code of conduct, communicates expectations and helps manage contributions.

Licence

State it, clearly, near the bottom or with a badge, and include the licence file. Without a licence, others generally have no clear permission to use your work. Guides to choosing a licence describe simple options, from short permissive licences to ones that require shared improvements. Choose deliberately, and name it.

Credits and changes

Thank people who helped. Link to a changelog where you record notable changes by version, in a human-readable list. A changelog tells users what changed between releases, and conventions for keeping one recommend grouping entries by added, changed, fixed and removed. It makes updating less scary.

Write for scanning

Most visitors scan before they read.

• Headings that say what the section is.
• Short paragraphs.
• Lists where there are steps or options.
• Code in code blocks.
• Bold sparingly for key terms.
• A table of contents only if the README is long.
• Plain words.

Accessibility counts, too. Use meaningful link text, give images alt text, keep headings in order and avoid conveying meaning by colour alone. The Web Content Accessibility Guidelines offer a framework that applies to documentation as well as websites.

Show, do not claim

Avoid unprovable boasts: "blazing fast", "the best", "production ready" with nothing to support it.

• If it is fast, show a measurement, with how you measured it.
• If it is stable, point to the tests and the version history.
• If it is secure, describe what you have done and what you have not.

A project that is honest about its limits attracts better users than one that overstates.

Keep it honest and alive

A stale README damages trust.

• Update it when behaviour changes.
• Mark the status. If you are no longer maintaining the project, say so at the top.
• Remove dead links.
• Date important statements that could go out of date.
• Ask a newcomer to follow it and note where they trip.

If the project is archived or retired, say so plainly, and tell people where to go next, if anywhere.

Beyond the repository

The README is not the only place your project lives. A short page on your own site, a listing on a launch platform and a post about how you built it all point people in. Keep their descriptions consistent with the README. The one-sentence description should be the same in each.

A listing on a launch platform, such as through the submit page here, gives a project a permanent public page that links to the README, which suits side projects that live mostly in a repository.

A README outline to copy

1. Name and one-sentence description.
2. Screenshot or example.
3. Link to a demo or quick install command.
4. What it is, who it is for, what it is not, current status.
5. Getting started.
6. Usage and examples.
7. Configuration.
8. Help.
9. Contributing.
10. Licence.
11. Credits and changelog link.

Fill in only the sections you need. A short README for a small project is perfectly fine.

Common mistakes

• Starting with history instead of purpose.
• No proof it works.
• Install steps that no longer work.
• No licence.
• Vague boasts.
• A wall of text.
• No status or maintenance note.
• Never updating it.

On this site

The submit page lets you create a listing that links to your README, the launches page shows how other makers present their projects and the developers page describes the free API and MCP server. The categories page helps you find a shelf, and the blog has more guides for makers.

A README in prose, to show the shape

Imagine a README for a small tool that turns a folder of recipes into a shopping list. At the top is the name and one sentence. Below it is a short clip of the command running and a plain list appearing. Then three lines: who it is for, what it does not do and the current status, which is stable for the main case and experimental for scaled quantities. Next come two install commands and a first example with its output. After that, a small table of options with defaults, a line on where to ask for help and a note that contributions are welcome if they keep the project small. At the end sit the licence and a link to the changelog.

A newcomer can read the top in ten seconds, run the example in two minutes and decide in five whether it suits them. That is the whole job of a README, and it is mostly a matter of putting the right things first and removing the rest.

Test it on a stranger

The most honest test is to hand the README to someone who has never seen the project and say nothing. Watch what they do. Where they hesitate, add a sentence. Where they skip, cut. Where they ask a question, put the answer in. One session with one person improves a README more than a week of solitary polishing.

The short version

The README is the shop window. Open with a clear name, a one-sentence description, proof that it works and a way to try it, then say what it is and is not, give tested getting-started steps and examples, point to help and contribution guidance, name the licence and credit people. Write for scanning, show rather than claim, mark the status and keep it alive. Ten good seconds at the top earn the rest of the read.