Show HN README Checklist: What to Fix Before You Post (+ Template)
A section-by-section checklist for getting your GitHub README ready for a Show HN post. It includes a fill-in template and a before-and-after example.
When your project is on Show HN, your README may be doing the job of a landing page, a manual and a first impression. You won't be there when someone opens it. They have to work out what the project does and get it running on their own.
The Show HN rules say a post should be something people can try, and they ask you to make that easy, ideally without barriers such as signups or emails. Reading material and sign-up pages are off topic. Those rules can change, so read the current version on Hacker News before you post.
The rest of this page is editorial advice from a README service, not official Hacker News guidance. No README guarantees votes or stars. A good one simply removes reasons for an interested person to give up.
Set aside about an hour. Go through the checklist in order, because the top of the page matters most.
Part 1: The first screen
Open your repo in a private browser window, so you see it as a stranger does. Without scrolling, a reader should be able to answer three questions: what is it, who is it for, and how do I try it?
- [ ] The first sentence says what the thing is. Use a plain noun: "A command-line tool that...", "A Postgres extension that...", "A self-hosted app that..."
- [ ] The sentence names the job it does. "Removes old lines from huge log files" beats "Log management, reimagined."
- [ ] Hype is gone. Search for blazing, revolutionary, seamless, next-generation, powerful and effortless. Replace each one with a fact or delete it.
- [ ] Badges are few and true. Keep the ones a user acts on, such as build status, latest version and license. A failing or broken badge is worse than none.
- [ ] There is one picture of it working, if it has any visible output: a screenshot, a short GIF or a pasted terminal session. Open the README while logged out to confirm the image loads.
- [ ] The GitHub "About" box is filled in with the same one-line description.
Part 2: Try it in one copy-paste
This section decides whether people get past reading.
- [ ] Prerequisites come first, with versions. "Requires Python 3.10 or newer" is usable. "Requires Python" isn't.
- [ ] There is one recommended install path. Put alternatives below it or under an "Other install options" heading.
- [ ] Commands can be pasted as they are. Remove any `$` prompt from the start of a line, and put output in a separate block.
- [ ] Placeholders are obvious. Say what to replace, and use a working example value where you can.
- [ ] Every required environment variable or API key is mentioned before it's needed.
- [ ] There's a way to try it without an account, if the product can support one: a demo mode, sample data, a local run or a public demo.
- [ ] Expected output is shown, so people know the command worked.
- [ ] Your supported platforms are stated. If you've only tested on Linux and macOS, say so. Don't leave Windows users to find out.
- [ ] You've run every command on a clean machine. Your laptop has packages, caches and environment variables that a new user won't have. Run the commands in a fresh container or virtual machine, exactly as the README shows them.
Use a stopwatch for the last item. Decide what a fair time to first result is for your kind of project, then time it. If the wait is long because of a large build or download, warn readers and give a rough time.
Part 3: Honest answers to the obvious questions
Technical readers tend to ask the same things. Answer them before someone has to ask in the thread.
- [ ] Why this over the existing option? Name the alternative and give a specific difference. Say where the alternative is the better choice.
- [ ] What's its status? Experimental, usable or in production? Is the API stable?
- [ ] What doesn't it do? A short "Limitations" list earns more trust than silence.
- [ ] Does it send data anywhere? State what leaves the machine, including telemetry, and how to turn it off. If nothing leaves, say so, once you've checked.
- [ ] Are performance claims reproducible? Give the hardware, the data and the command. If you can't, remove the number.
- [ ] What does it cost? If there's a paid tier or hosted version, say what's free and what isn't.
- [ ] Did you use AI to build it? If that's relevant to how far people should trust the code, be upfront about it.
Part 4: Repo hygiene
- [ ] A LICENSE file exists, and the README names the license. Without a license, people have no clear permission to use your code.
- [ ] Every link and image works, including anchor links within the page.
- [ ] Docs match the current release. Check flag names, default values and version numbers against the code.
- [ ] Secrets aren't committed, including in example config files and git history.
- [ ] Issues are open, and the README says where to report bugs.
- [ ] Leftovers are gone. Search for TODO, lorem ipsum, "coming soon" and the default text from your project generator.
Fill-in README template
Copy this, replace everything in square brackets, and delete any section that doesn't apply.
```
[Project name]
[A/An] [type of thing] that [does what] for [whom].
[Screenshot, GIF or terminal output]
Why
[The problem, in one or two sentences.] Unlike [existing option], it [specific difference]. Use [existing option] instead if [honest condition].
Try it
Requires [runtime and minimum version]. Tested on [platforms].
[one install command] [one command that produces a visible result]
You should see:
[real output, copied from a clean run]
Usage
[the most common real command] [the second most common real command]
Configuration
| Option | Default | What it does | |--------|---------|--------------| | [name] | [value] | [plain description] |
Status and limitations
Status: [experimental / usable / production]. It doesn't [limitation 1] or [limitation 2]. Data: [what leaves the machine, or "nothing leaves your machine"].
Contributing
Report bugs in [location]. To work on it locally: [command].
License
[License name] ```
Worked example: before and after
This example uses a made-up tool called logtrim.
Before:
```
logtrim 🚀
The next-generation, blazing-fast solution for modern log management.
Installation
$ git clone [repo] $ make $ ./setup.sh Edit the config, then run it. ```
The opening doesn't say what the tool does. The prompts break copy-paste, "the config" is never explained, and a reader has no sign of what success looks like.
After:
```
logtrim
A command-line tool that removes old lines from large log files without loading the whole file into memory.
Why
Log rotation works on whole files. logtrim keeps the most recent period inside one file. If you already rotate logs and that's enough, you don't need this.
Try it
Requires Python 3.10 or newer. Tested on Linux and macOS.
pipx install logtrim logtrim --demo
You should see:
Created demo.log (1,000 lines) Kept 120 lines from the last hour Removed 880 lines
Status and limitations
Status: usable, flags may change before 1.0. It doesn't handle compressed logs or files being actively written. Data: nothing leaves your machine. ```
The new version doesn't claim to be fast or modern. It says what the tool does, who shouldn't bother, and how to get a result with two commands.
The final test
Ask someone who hasn't seen the project to open the README and try it while you watch, without helping. Note each place they pause, scroll back or ask a question. Each one is a line to fix.
If nobody is available, come back to it after a break, follow the page literally on a clean machine, and do only what it tells you to do. Anything you had to do from memory belongs in the README.
Once the README holds up, write your post's first comment: how you came to work on the project and what's different about it. The Show HN rules suggest it, and the README's "Why" section gives you most of the material.
Browse the Quillwork shop