Email us at hn@ycombinator.com if you want some tips about how to present this to HN. (Same invitation goes for everybody who wants such tips.)
Edit: here's what I sent the users who emailed:
If you're sharing
your own work and there's a way to try it out, put "Show HN" in
the title. Make sure you've read the Show HN guidelines: https://news.ycombinator.com/showhn.html.
Include text giving the backstory of how you came to work on this, and explaining what's different about it. That tends to seed discussion in a good direction. (Your text should show up at the top of the Show HN submission, but if for some reason it doesn't, add it as a first comment to the thread. Either way is fine.)
Include a clear statement of what your project is or does. If you don't, the discussion will consist of "I can't tell what this is".
Include links to any previous HN threads that are relevant. Readers like those.
Drop any language that sounds like marketing or sales. On HN, that is an instant turnoff. Use factual, direct language. Personal stories and technical details are great.
For Show HN, the product/project needs to actually exist and there needs to be a way for people to try it out. It can't just be a landing page or market test or fundraiser or a blog post or a curated list or other reading material. Please respect this rule. If we allowed "Show HN" on all those things, nearly every post would be a Show HN.
Please make it easy for users to try your thing out, preferably without having to sign up, get a confirmation email, and other such barriers. You'll get more feedback that way, plus HN users get ornery if you make them jump through hoops.
If it's hardware or something that's not so easy to try out over the internet, find a different way to show how it actually works—a video, for example, or a detailed post with photos.
Don't have your username be that of your company or project. It creates a feeling of using HN for promotion and of not really participating as a person. You don't have to use your real name, just something to indicate that you're here as a human, not a brand. If you'd like to change your username, email hn@ycombinator.com.
If you're comfortable doing so, put your email address in your profile so we can
contact you if we notice anything, and also so
we can send you a repost invite. We do that sometimes.
Make sure your friends and users do not add booster comments in the thread. HN users are adept at picking up on those, they consider it spamming, and they will flame you for it. If a friend or a fan has something interesting to say, that's fine, but comments should not be promotional.
You can post a new release as a Show HN only if the new version is significantly different. It shouldn't just be an incremental upgrade. If you do repost, add a comment linking to the previous Show HN and explaining what is different from last time. This should probably only happen once or twice a year—more starts to be excessive.
This looks like it is written by someone who knows marketing but still doesn't quite get developers. They have developed some guidelines for what works, likely through trial and error, but don't quite understand why.
Devs simply want transparency. Marketing tends to come from a perspective of having to "capture" the market, instead of just informing the market.
Look at how it works on HN. People say, "I'm self promoting: Fixing pain X with solution Y. Here's is some info."
Don't over-do marketing. Just state the facts. Don't try to be coy about the fact that you are marketing a product. Just say so. And don't waste our time. Start with the pain that your product solves so we know whether to even spend 3 seconds looking at it, and then just say how it solves the problem.
But if you are giving bulleted lists of dos and dont's and saying things like 'devs love swag' you've already missed the mark. Just talk to us as if we are fellow human beings.
I'd say another rule of thumb, which may not be specific to developer marketing, is to avoid the "used by" pitfall. I often see tools that were launched, like, a month ago claiming that it's "loved by teams at Uber/Slack/etc". What I imagine in those scenarios is that there's an intern who signed up for a beta using their company email, and the founders were like "hey good enough, technically we're now used by teams at [x] company!" I can see through it, and I'm sure others can as well.
It comes off as disingenuous. A better way is to tell a specific success story. If some unknown brand has a story to tell about how your tool 10x'd their productivity, I'm all ears.
A good description of what the project does, installation instructions, and decent example usage where appropriate.
I like to show:
1. What it is.
2. How to install it.
3. What command-line flags there are, for CLI apps, or what the API is for embedding if a shared library.
4. Notes on how to run the tests.
5. A comment about reporting bugs.
Some projects have more sections, others less, but I think clear instructions for downloading/using, as well as a "What even is this?" is a good start.
Set the hook. Love to have the TLDR, INSTALL and dependency info upfront. Do anything you want after that, but first I want to be on board with the basic premises.
Edit: here's what I sent the users who emailed:
If you're sharing your own work and there's a way to try it out, put "Show HN" in the title. Make sure you've read the Show HN guidelines: https://news.ycombinator.com/showhn.html.
Include text giving the backstory of how you came to work on this, and explaining what's different about it. That tends to seed discussion in a good direction. (Your text should show up at the top of the Show HN submission, but if for some reason it doesn't, add it as a first comment to the thread. Either way is fine.)
Include a clear statement of what your project is or does. If you don't, the discussion will consist of "I can't tell what this is".
Include links to any previous HN threads that are relevant. Readers like those.
Drop any language that sounds like marketing or sales. On HN, that is an instant turnoff. Use factual, direct language. Personal stories and technical details are great.
For Show HN, the product/project needs to actually exist and there needs to be a way for people to try it out. It can't just be a landing page or market test or fundraiser or a blog post or a curated list or other reading material. Please respect this rule. If we allowed "Show HN" on all those things, nearly every post would be a Show HN.
Please make it easy for users to try your thing out, preferably without having to sign up, get a confirmation email, and other such barriers. You'll get more feedback that way, plus HN users get ornery if you make them jump through hoops.
If it's hardware or something that's not so easy to try out over the internet, find a different way to show how it actually works—a video, for example, or a detailed post with photos.
Don't have your username be that of your company or project. It creates a feeling of using HN for promotion and of not really participating as a person. You don't have to use your real name, just something to indicate that you're here as a human, not a brand. If you'd like to change your username, email hn@ycombinator.com.
If you're comfortable doing so, put your email address in your profile so we can contact you if we notice anything, and also so we can send you a repost invite. We do that sometimes.
Make sure your friends and users do not add booster comments in the thread. HN users are adept at picking up on those, they consider it spamming, and they will flame you for it. If a friend or a fan has something interesting to say, that's fine, but comments should not be promotional.
You can post a new release as a Show HN only if the new version is significantly different. It shouldn't just be an incremental upgrade. If you do repost, add a comment linking to the previous Show HN and explaining what is different from last time. This should probably only happen once or twice a year—more starts to be excessive.