Orviqa

How to launch an open-source project on Show HN

By Bright Oparaji9 min read

A Show HN post works when a stranger can try your project within a minute of clicking, and you are there to answer what they ask. Most of the rest is following rules that are short, public and routinely ignored.

Read the three pages before anything else

Hacker News publishes its rules in three places, and a Show HN launch touches all of them. The Show HN guidelines say what counts as a Show HN at all. The general guidelines cover titles, promotion and conduct. The FAQ explains ranking, flags and reposts.

They take about ten minutes to read together. Reading them is the cheapest thing you will do for your launch, and the mistakes they warn against are the ones that get posts flagged.

Check that your project qualifies

Show HN has a narrower definition than people assume. The guidelines describe it as a place for things people can run on their computers or hold in their hands. An open-source library, a command-line tool or a self-hostable app fits. A few things do not:

  • Blog posts, newsletters, sign-up pages and lists. These cannot be tried, so the guidelines ask you to submit them as ordinary stories instead.
  • Landing pages and fundraisers. The project has to be usable now. If it is not ready, the advice is to come back when it is.
  • Routine releases. A point release is usually not enough for a new Show HN. A major overhaul may be. Where else a release can go is in how to announce an open-source release.
  • Someone else's work. The project should be something you made yourself, and you should be around to talk about it.

The guidelines also say the work should be non-trivial, and that quick one-off projects are not what Show HN is for. Early or rough work is explicitly fine. The bar is that it exists, it is yours, and someone can use it.

That last point is easy to agree with and easy to miss. The guidelines ask you to make the thing easy to try, ideally without sign-ups or email gates. For an open-source project, the equivalent barrier is a README that makes a visitor work out how to get from the repository page to a running example. Which leads to the step most launches skip.

Fix the README before you post

Almost every click from a Show HN post lands on your repository or your docs. The visitor arrives curious and in a hurry, and the first screen decides whether they stay. A README has about ten seconds to say what the project does, who it is for and whether it works, and a launch is the one day when the most people will test that at once.

Before you post, check three things:

  1. The first sentence says what the project does, in words a reader outside your problem would understand. Not a category. A capability.
  2. A runnable example appears on the first screen. An install line followed by nothing does not count. Show the first command and what it prints.
  3. Nothing stands between the reader and trying it. No account, no API key you have not explained, no "see the docs" link where a code block should be.

If you want a second opinion that is not your own, the free README grader scores a README from 0 to 100 on a published rubric that starts with the same questions. Orviqa runs a fuller version of that check across a whole repository, which is useful the week before a launch, though the three questions above will catch most of what matters.

A good README does not make a Show HN succeed. A weak one can quietly waste a launch that was otherwise fine, because the people who would have become users leave before reaching the part that would have convinced them.

Write a plain title

Every Show HN title starts with "Show HN:". After that, the general guidelines ask you not to make titles stand out with capitals or exclamation marks, and not to editorialise. That rules out most of what launch advice elsewhere recommends.

A plain title says what the project does in a short statement, with its name if the name helps. Two invented examples:

  • "Show HN: A local queue for Python tasks that survives restarts"
  • "Show HN: A CLI that diffs two Postgres schemas and writes the migration"

A title that does not work leans on adjectives or claims: "the fastest", "a better way to", "finally". They are the editorialising the guidelines ask you to leave out, and readers tend to discount them anyway. If the project is faster than an alternative, say so in the first comment with the benchmark, where a reader can check it.

Write the first comment before you submit

The Show HN guidelines ask you to explain how and why. In practice that means a comment from you on your own post, written in advance so you are not composing it in a hurry while the post sits on the new page.

A useful first comment covers four things, briefly:

  • What it is and who it is for, in two or three sentences.
  • Why you built it. The problem you had, and what you tried first. This is the part that tells a reader whether their problem is the same as yours.
  • How it works, at the level an engineer would want. The interesting design decision, the trade-off you made, the thing you are unsure about.
  • What state it is in. What works, what does not yet, and what kind of feedback you want.

Keep it to a few short paragraphs. Do not paste the README. Do not ask for stars. And be honest about the rough edges, because someone will find them within the hour, and it reads far better if you named them first.

Do not ask anyone to upvote

This is the rule that matters most, and it appears on all three pages. The Show HN guidelines say not to ask friends to upvote or comment. The general guidelines say not to solicit upvotes, comments or submissions. The FAQ answers the question directly: no, people should vote because they find a story interesting, and the site penalises or bans submissions, accounts and sites that break the rule.

That includes the soft versions. A message to a group chat saying "we're on HN, have a look" is a request for votes, whatever the wording. So is a tweet linking straight to the post. If you want to tell people you launched, link to the project, not to the discussion.

Related: the general guidelines say it is fine to post your own work some of the time, but that the site should not be used mainly for promotion. If your account exists only to submit your own project, that pattern is visible. An account with a history of ordinary participation reads differently. The FAQ also notes that new accounts are shown with green usernames, so readers can see when an account is new.

After you post

Every Show HN appears on the shownew page, according to the guidelines, and moves to the main show page once it passes a points threshold. The FAQ describes ranking in one line: points divided by a power of the time since submission, adjusted by flags, anti-abuse software and moderators. Early attention matters more than late attention, which is the honest reason to have your first comment ready and to stay at your desk.

For the next few hours:

  • Answer every substantive comment. The Show HN guidelines say you should be available to discuss the work. A question answered well is often worth more than the post itself, because it is what later readers see.
  • Take criticism as information. Someone pointing out a competitor you have not heard of has done you a favour. Thank them and say how yours differs, or say it does not.
  • Fix small things live. A broken link or a confusing install step that someone reports can be fixed in minutes, and saying so in the thread shows the project is maintained.
  • Do not argue about votes or flags. The guidelines ask people not to comment about voting, and it never helps.

When the thread has gone quiet, read what the post did against your project's usual week, not against the morning's excitement: did my launch post work? sets out a method.

If it sinks

Most posts get little attention. That is normal and says less about your project than it feels like it does.

The record from one maintainer we studied makes the point. Over six weeks of promoting an open-source tool, the maintainer made three Show HN submissions. The best reached one point, and two of the three were flagged. The same period produced other results that were more visible, including an essay that scored one point on Hacker News and was then picked up by a newsletter ten days later. The full write-up is careful about what that data can and cannot show, and the honest summary is that one room ignoring something tells you very little about the thing.

What you should not do is delete and repost. The FAQ asks people not to, and says reposts are buried as duplicates. It does allow a small number of reposts of a story that has had no significant attention in the last year or so. The practical reading is: if a Show HN gets nothing, improve the project, and come back with a later post when there is something substantially new to show.

If a post is flagged or marked dead, read the guidelines again with that post in front of you. The FAQ says a flag means users thought the post broke the guidelines or did not belong on the site. Something in the title, the format or the account history is often the reason, and posting the same thing again with new wording will not change it.

Where Show HN fits

Hacker News is one room. It suits projects that engineers can run and judge on the spot, and it rewards plain description and a maintainer who turns up for the questions. It is not the only launch, and for many projects it is not the best one. The guide to promoting an open-source project and the open-source launch checklist cover the other places, and how to tell which ones your users are actually in.

Wherever you post, the visitor ends up on the same page. Get that page right first, then go and show it to people.

← All posts