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?

Part 2: Try it in one copy-paste

This section decides whether people get past reading.

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.

Part 4: Repo hygiene

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.

More templates and kits
Browse the Quillwork shop