Show HN: How we built our interactive demo walk-through

At our end, we have no way of distinguishing between people soliciting votes and comments to manipulate HN vs. friends and fans just feeling supportive and trying to help out. From an HN point of view, the distinction doesn't much matter. We want people to vote for a story because they ran across it and personally found it intellectually interesting, not because they or their friends have content to promote. This is in the FAQ: https://news.ycombinator.com/newsfaq.html.

The larger issue, though, is the booster comments. Promotional votes at least don't do much visible damage, but promotional comments do, and after a few of them, the thread becomes unsalvageable. When friends or coworkers post booster comments, trying to sound like ordinary users who just happened to love the article, they mean well but are hurting both you and HN. They're hurting you because HN readers are highly sensitive to this, usually pick up on it, and then switch into attack mode. They'll make that the issue ("spamming", "manipulating", etc.) rather than your work. And it's bad for HN, obviously, because it degrades quality. Discussions here are supposed to be for intellectual curiosity, and booster comments are not interesting. And for this community to function, users need to be able to trust each other.

That said, if you genuinely want to participate in the community here, you're welcome! All of you are. This isn't the bannable spam kind of thing, it's a case of people doing interesting work but trying to plug it into HN the wrong way.

In terms of your article: (1) you should introduce yourself and your company at the beginning so readers can tell who you are and what you do. The discourse here is largely stateless, so each 'packet' has to come with identifying info. (2) We've learned over the years that tutorials ('step 1 do this, step 2 do that') are not a good fit for Hacker News. A good HN story gratifies the curiosity of a random smart reader; a good tutorial makes a task simple, but probably won't interest anyone who isn't trying to do that task. These are two different audiences, so the two formats work differently. A recipe is useful when you want to cook that dish, but not so good for general interest, so for HN, don't frame your material as a recipe, frame it as a story: "we needed to do X so we tried Y, had trouble because of Z, solved it with W, and oh by the way have some surprising details A, B, and C".

If you want to rework the article a bit and repost it, you'd be welcome to. It would be good to wait a week or two before doing that. You can email us at hn@ycombinator.com and we might be able to give you a bit more feedback, and also make sure that the repost doesn't get flagged.

Edit: Two more thoughts for you popped into my head.

(1) You need to movitate the problem more. When I skim your article, it's about how to build a kind of widget; but what is this widget and what's its value? You hint at this with the term "interactive demo", but that's not enough to attract the reader. By jumping too quickly to how you did it, without first establishing what and why, you make the article's appeal smaller than it should be. Readers have an early warning radar system called "why should I care" and your article's success depends on registering some signal on that radar. You have perhaps two seconds to do that, i.e. two seconds after they click and before they close the tab. Don't resort to flashy design tricks or urgent language to get attention in those two seconds—readers are inured to all that and it backfires. You have to do it with something genuinely interesting.

What we tell YC startups all the time is: when addressing HN, you need to appeal to intellectual curiosity. It's easy to assume that people know what your widget or product or idea or company is, because you know what it is. But almost no one else does. That's the hugest mistake people make and the easiest to fall into. Instead, draw the reader in by talking about the problem you're solving and why that problem is important. Alternatively, you can draw them in with the 'just for fun' approach: "I wanted to do weird-thing- X. Why? Just because. And it turns out if you want to do weird-thing-X the first issue you encounter is Y." etc. But your article shouldn't take the just-for-fun approach because it targets an important problem... even though most people wouldn't notice, which is the next point:

(2) Your article buries the lead [1], i.e. it drops a mention of the Most Important Thing in an obscure place and never comes back to it. What you ought to do, of course, is put the Most Important Thing in first position. Here it is:

> a hugely positive impact on our conversion rate

Thousands of HN readers, the ones who are trying to increase their own conversion rates as well as others who are just interested in the question, perk up when they hear a claim like that. Of course they will also perk up their skepticism—but that's good if you can back it up. So if that's what your widget has gotten you, you can 10x your article's appeal by leading with that and working your way backward from there. Eventually you can get into the how part, and by then, readers will be drawn in enough to want those interesting technical details. But don't present them in recipe format (1, 2, 3). Frame it as a story, as explained above.

1. https://www.merriam-webster.com/words-at-play/bury-the-lede-...

I will admit something too then, I am not a JQuery fan but I can't fault your use of it here. Right tool, right job. I would still prefer to use my favourite 'only the bits I need' MooTools - but alas, fashion wins ;)