Roughly half the articles on the blog I run for Rock carry something the reader can use. A quiz that narrows a shortlist, a framework you fill in, a timer that runs. The BuzzFeed quiz was onto something makes the case for why that matters now.
You pick a format, hand the agent a brief that gets a first version, then put in the back and forth that makes it shippable. A quiz takes me half an hour now, while something new from scratch takes me closer to an hour.
Below is an example from an article I wrote a few weeks back on the Pomodoro timer. It is a pretty easy concept, so show-don’t-tell seemed like a good strategy to get some SEO differentiation and stand out from the crowd.
Pick the format from the reader’s question
There are a few different builds that can go on a blog page depending on what the reader came looking for. Here are five different intents within the scope of this tutorial:
- “Which of these fits me?” wants a recommender quiz.
- “How do I do this?” wants a builder they fill in.
- “What does this cost me?” wants a calculator.
- “What are my options?” wants a comparison table.
- “Show me how this actually runs” wants a demo.
It took me a few passes to get this right. In general I would recommend playing around with the concept on your blog as you go. Start with a table or a simple quiz, and build out to deeper product-led growth concepts as you get more comfortable coding out widgets.
The quiz below runs that rule for you, and doubles as this tutorial’s worked example. It started from the brief in the next section, and everything it recommends is live on a real page.
Four questions about the article you have open. Nothing is stored, and the result appears once all four are answered.
What is your reader actually asking when they land?
What should they be holding when they leave?
What kind of page is this?
How much are you willing to build?
The opening brief, and the twenty minutes after it
A widget is not really one prompt. An opening brief gets you a rough version, and then about twenty minutes of back and forth make it something you would put your name on.
Start with the brief below. Then read the honest account of what happens next, because that part is where the work actually is.
Assignment: brief your first widget
Pick your format, then fill in the brackets before you paste. The prompt changes in one place, the content section. That section is where the quality comes from, so answer it as if you were briefing a writer rather than a developer.
A recommender quiz asks a few questions and hands back the option that fits, with the reasoning. The one above that picked your format is exactly this build.
Build a recommender quiz I can paste into one blog article.
The page: [topic]. The reader arrives asking [the exact question,
in their words]. They should leave with [the outcome].
Content: four questions, each with three to five options in plain
language. Every result needs a plausible option in at least one
question, or the reader who wants it has nothing honest to click.
Score the answers toward [list your possible results].
Each result gets one line on why it fits, a best-for line, a
skip-it-if line, and a link I will fill in.
Build rules:
- one self-contained file, plain JavaScript, no dependencies
- prefix every class with [xy-] so nothing collides with the page
- one click handler on the container, not one per option
- options are divs with a button role and tabindex, never <form>,
<input> or <button>
- taps work everywhere; nothing is drag-only
- tap targets at least 44px tall
- no result until all four questions are answered, and the call to
action appears with the result, never before
Ask me anything you need before you write it.
A builder turns a framework into inputs the reader fills in, then hands back the assembled result to copy into their own doc. They leave holding the thing rather than a description of it, which is the entire point.
Build a builder I can paste into one blog article.
The page: [topic]. The reader arrives asking [the exact question,
in their words]. They should leave with [the outcome].
Content: the framework’s fields as inputs, with a placeholder
example in every field. The result assembles them into the
finished [artifact], with a copy-to-clipboard button so the
reader leaves holding it.
Build rules:
- one self-contained file, plain JavaScript, no dependencies
- prefix every class with [xy-] so nothing collides with the page
- one click handler on the container, not one per option
- options are divs with a button role and tabindex, never <form>,
<input> or <button>
- taps work everywhere; nothing is drag-only
- tap targets at least 44px tall
- the call to action appears with the result, never before
Ask me anything you need before you write it.
A calculator takes the reader’s own numbers and turns the article’s claim into their number: their rate, their hours, their bill. Defaults matter more than they look, because one that opens on zeroes shows the reader nothing and asks them to work first.
Build a calculator I can paste into one blog article.
The page: [topic]. The reader arrives asking [the exact question,
in their words]. They should leave with [the outcome].
Content: numeric inputs for the numbers the reader already
knows, with sensible defaults filled in, never zeroes. The
result turns [the article’s claim] into their own number.
Build rules:
- one self-contained file, plain JavaScript, no dependencies
- prefix every class with [xy-] so nothing collides with the page
- one click handler on the container, not one per option
- options are divs with a button role and tabindex, never <form>,
<input> or <button>
- taps work everywhere; nothing is drag-only
- tap targets at least 44px tall
- the call to action appears with the result, never before
Ask me anything you need before you write it.
A comparison table lays the options out side by side so the reader can scan criteria instead of holding them in their head. Past about four columns it stops being scannable on a phone and gets skipped whole.
Build a comparison table I can paste into one blog article.
The page: [topic]. The reader arrives asking [the exact question,
in their words]. They should leave with [the outcome].
Content: the options as rows and the criteria as columns,
capped at about four. Plain language in every cell. If it
needs more columns, split it into two tables by theme.
Build rules: none needed. It is just HTML.
Ask me anything you need before you write it.
A demo is a working miniature of the thing itself, like the timer at the top of this page: the reader plays with it rather than reading about it. Showing how the workflow moves beats describing it, and it is the most work of the five.
Build a demo I can paste into one blog article.
The page: [topic]. The reader arrives asking [the exact question,
in their words]. They should leave with [the outcome].
Content: the interaction states of [the workflow you are
showing], with no scoring and no result. The interaction
itself is the argument.
Build rules:
- one self-contained file, plain JavaScript, no dependencies
- prefix every class with [xy-] so nothing collides with the page
- one click handler on the container, not one per option
- options are divs with a button role and tabindex, never <form>,
<input> or <button>
- taps work everywhere; nothing is drag-only
- tap targets at least 44px tall
- no call to action until the reader has interacted
Ask me anything you need before you write it.
I have added a few placeholder rules so you get a solid starting point. Finetuning the widget requires your own product and growth knowledge. The widget needs to align with your positioning, messaging and branding; and if you’re doing a product-led object, truthful to your UI/UX.
There is no guide that applies to everyone. Test it out, show it to a coworker, collect some data, or even tag me on X with what you’ve built if you’re looking for feedback and more tips!
Expect the first version to be bad
The version that comes back from that brief will run, and it will look generated. Rounded cards with drop shadows, a stray gradient, padding that belongs to no other element on your site, copy that sounds like a product tour. Readers clock that instantly, and a page that reads as machine-made gets closed faster than it loaded.
So budget for the second half. Roughly twenty minutes of going back and forth, on:
Some ideas do not survive this stage, and that is the system working. A fair number of concepts are obviously wrong the moment you see them rendered. Scrapping one costs half an hour now, which is why it is worth trying the uncertain ones at all.
Check it before it ships
Three checks, in the order that catches the most damage:
Half an hour covers a format you have built before. The time goes into copy and styling rather than code, which is the part worth your attention anyway.