
Show HN: How we built our interactive demo walk-through - hjkm
https://trevor.io/public/blog/demo
======
dang
This is a good article but unfortunately there's evidence of voting collusion
and, worse, booster comments in the thread. We ban accounts and sites that do
these things, so please make sure not to do them. It's not in your interest
anyhow, since if the article gets attention, HN readers are good at sniffing
out the collusion and then they go mad with ire.

~~~
trevz
Hi dang. Truly appreciate your feedback on this.

We have certainly been overwhelmed by the supportive comments of friends in
this case, but it was only our intention to start the conversation - not to
collude on votes (I don't have enough friends for that :-) ).

We spent a lot of time on this article, and were particularly excited to get
feedback on it from the HN community. Sorry if it has come across as anything
different.

~~~
dang
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](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 the tutorial format
('step 1 do this, step 2 do that') is 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-...](https://www.merriam-webster.com/words-at-play/bury-the-lede-versus-
lead)

~~~
hjkm
Just to jump in, this is really great information (not just for posting on HN,
but for writing articles / sharing lessons learned, in general) - many thanks
for taking the time.

------
simonmorley
Love this. Totes getting bored using a gazillion tools to help onboard my
users. Before you've even started a new venture, you'll find yourself hunting
for the right tool for a job you didn't even expect would exist.

Which support tool. Which analytics tool. Which AB testing tool. Which wizard
tool. bla bla bla.

Back to basics. I'll get my coding hat on and actually make an effort. Nice
work. Will try this one myself next time I need a wizard.

------
redroot
I'm interested to hear what the opinion on jQuery are like these days. Even if
it's a little unglamorous, this is the perfect use case - a one-off project
where you have needs for cross-browser animation, resizing, DOM manip, and
where something like React might be overkill, even if feasible. CSS animations
might be an alternative but it depends on audience browser breakdown.

~~~
trevz
Have to admit - we were a bit nervous about telling the world we used jQuery
for this. ;) But it still has its place IMHO.

~~~
RealCodeBeard
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 ;)

------
elsurudo
Nice – what a simple, elegant solution. Like the others are saying, sometimes
there's no need to reach for the heavy toolbox...

How did you measure the effectiveness of having the walkthrough on the front-
page? Did you (or did you think about) hooking this up to some analytics?
Perhaps see where people tend to drop-off?

~~~
hjkm
Yeh we have it hooked up to Mixpanel so we know exactly where people drop off.

As for its effectiveness, this is always a bit tricky for SaaS, not least
because the consideration stage tends to be quite long and people flick
between devices, which makes attribution a bit of a nightmare. We’ve done some
pretty obvious stuff, like comparing our sign up rates before and after adding
the demo / recording whether people who sign up have done it etc, which is
useful to know - though not always accurate.

More anecdotally, we spend a lot of time speaking with users and visitors and
the demo comes up surprisingly frequently (including how we made it, which is
why we wrote the post!) - it’s been a pretty quick, straight forward way of
showcase Trevor’s interface.

Shortly, we’ll be adding several new steps that demo features that are
commonly used by our existing customers.

Any thoughts about what else we might do / how others measure success?

------
maxnov
Very interesting. I think it's nice to see an account of building something
from scratch instead of using a library. Sometimes I spend more time searching
for a suitable library than it would take to build it from scratch :D

~~~
vshulyak
Yeah, we need more articles like this on HN. I see lots of libraries promoted,
instead of clean vanilla solutions like this one.

------
philgooch
Thanks for your generosity in sharing this, I can see this being incredibly
useful for creating user onboarding, walkthroughs and demos. The timing of
this is perfect for me - thanks again!

------
sergiks
Looks very elegant! Great it does not require loading the app itself and is
easily embeddable in a web page. Calling the implementation a "vanilla" jQuery
made me smile )

------
rhnyc
This is really useful - have been looking for flexible way to demo WIP
versions of apps to clients. Thanks for sharing

------
weichx
I like idea of using images for this and not trying to wrangle the actual app,
much cleaner!

~~~
trevz
Thanks! Yeah, we played with the idea of making a demo version of the app, for
a long time. But it would have been a mega-project.

------
ds99bwood9
Wonder how this would look like if it was vanilla JS? More performant to boot.

~~~
timmothey
Yes, might be a bit faster, as you don't have to load all of jquery and the
animations add-on. Also: one could save a bit of code by using CSS animations
(i.e. for the pulsing circle).

However, as others already wrote: Although I'm all for VanillaJS (if JS is
even needed in the first place), I dig the simplicity of how it's coded. Very
minimal and extremely easy to adapt and set up. Most work is probably figuring
out what the optimal flow through an app is to showcase the most important
features to convert users. That's why we have marketing people - they do
wonders explaining our ideas to others :)

I'm currently working on a project with seven of my students and saved it as a
bookmark for later (we have to present our result to lots of people at the
end)

------
cbck
This is really cool! I've been looking for something like this to give an app
walkthrough without needing test data or a demo environment -- thanks guys!

------
RealCodeBeard
Loads have commented rightly on the simplicity (nay elegance) of the solution.
I can't fault the use of JQuery even if I have never been a fan. I also agree
that sometimes just building something as opposed to searching for someone
else's solution is the right choice. Especially when you look at some of the
foolish 'kata' time people spend when they could practice on something
business-useful like this.

Most of all, to see the thought process played out is really important. This
article would make great reading for juniors to help see how more experienced
people solve problems. Particularly as it is not a patronising 'tutorial'
(draw three circles, then draw an owl) but working through a clear scenario.

