Most developer landing pages read like a release note. The headline says something like "Built on Postgres, ships with a typed SDK, supports SSO and webhooks." Every word is true, and not one of them tells a stranger what the thing is or why they should care. You have described the engine and forgotten to mention it's a car.
This is the most common landing-page mistake builders make, and it comes from a good instinct: you are proud of the work, and the work is the architecture. So you lead with the architecture. But the visitor who just arrived from a tweet or a search result has no context. They have not read your README. They are giving you about three seconds to make the case, and you are spending those three seconds on your tech stack.
The good news is that converting visitors does not require manipulation, fake countdown timers, or dark patterns. It requires a clear answer to a small set of questions, delivered in the right order. This chapter is about that order — and the single screen that decides whether anyone reads the rest.
Look at the top of your own landing page right now. Read only what fits above the fold — the part visible before any scroll — and ask: could a smart stranger who has never heard of you say, in one sentence, what this product does and who it's for?
If the answer is no, you have the disease. And it usually shows up in one of three shapes.
The feature-dump hero: a headline that lists capabilities. "Real-time sync, offline-first, end-to-end encrypted." Capabilities are not a value proposition. They are the how, and the visitor has not yet bought into the what.
The clever hero: a headline so abstract it could belong to any company. "Ship faster. Build better. Move at the speed of thought." This says nothing. Swap your logo for a competitor's and the page still works, which means it isn't working.
The internal-jargon hero: a headline written for people who already use the product. "The control plane for your edge functions." If the reader needs to already understand your category to parse the sentence, you have lost everyone who doesn't.
Read your headline out loud to someone who doesn't work in your field — a friend, a family member, a barista. If they can't tell you roughly what you sell, the headline has failed, no matter how accurate it is. Accuracy is not the bar. Comprehension is.
The fix is not to write more. It's to lead with the one thing the visitor needs before anything else makes sense.
Everything on a landing page is in service of one job: getting the visitor to keep going. The first screen does not have to close the sale. It has to earn the second screen. If it fails, nothing below it gets read — your beautiful feature grid, your testimonials, your pricing, all of it scrolls past unseen because the visitor already left.
So the first screen carries more weight than the rest of the page combined. Treat it as a self-contained pitch.
The first screen, alone, must answer three questions — what is this, who is it for, and why should I care right now — and offer one obvious next action. If the first screen can't pass that test on its own, the rest of the page never gets read.
The OSP is four parts, and they map cleanly onto markup you already know how to write.
A clear headline — what it is, in plain language. Not the category, not the cleverness. The outcome. "Turn your API into a hosted docs site in one command" beats "Developer-first documentation infrastructure" every time, because the first one is a picture and the second is a word cloud.
A subhead — who it's for and the next layer of detail. This is where a feature or two finally earns its place, in service of the headline. "For backend teams who hate writing docs. Point it at your OpenAPI spec; we handle hosting, search, and versioning."
One call to action — a single, obvious next step. Not three buttons of equal weight. One primary action, styled loudest; this is the same discipline as One Primary Action and One Loudest Thing, applied to the most important screen you own.
A piece of proof — something that says other people trust this. A row of recognizable logos, a star count, a one-line testimonial, a real number. Even a small signal beats none, because the visitor's silent question under every claim is "says who?"
The first screen does not have to close the sale. It has to earn the second screen.
Here is the structure, stripped to its bones. Note how little there is — that's the point. The first screen is an exercise in subtraction.
<section class="hero">
<h1>Turn your OpenAPI spec into a hosted docs site</h1>
<p class="subhead">
For backend teams who hate writing docs. Point it at your
spec — we handle hosting, search, and versioning.
</p>
<a class="btn-primary" href="/signup">Generate my docs</a>
<p class="proof">Trusted by 2,400+ engineering teams</p>
</section>
One headline, one subhead, one button, one proof line. If you are tempted to add a second button, a feature list, or a screenshot carousel above the fold, resist. The screenshot can come immediately after the fold, where it confirms the promise the words just made.
If a stranger can't tell what you sell and why it's for them from the first screen alone, nothing below the fold will save you.
You already have the instinct for this. A good function name says what it returns, not how it's implemented. getActiveUsers() not iterateAndFilterUserArray(). Your headline is a function name for the whole product: it should name the result the user gets, not the machinery you built. This is Label the Outcome scaled up to the largest text on your site.
A quick rewrite drill — take any feature-led headline and ask "so the user can what?" until you hit a human outcome.
The plain-language version is what goes in the h1.
Below the fold, you are no longer pitching — you are making the argument. A landing page that converts reads like a well-structured proof, each section answering the question the previous one raised. There's a reliable order, and it's worth following because it matches how a skeptical reader actually thinks.
Problem. Name the pain in the reader's own words before you sell the cure. "You ship an API and then spend a week hand-writing docs that go stale the moment you add an endpoint." When a reader sees their exact problem described, they trust that you understand it — and trust is what they're really shopping for.
How it works. Three or four steps, or three or four core capabilities, each tied back to the problem. This is where features live, finally in context. Not "we support webhooks" but "get a Slack ping the moment a doc build fails." A feature is only interesting once the reader knows which pain it removes.
Proof. Now the heavier social proof — testimonials with names and faces, case-study numbers, logos with a sentence of context. The reader believed you might solve the problem; now you show them you already have, for people like them.
Objections. Every reader has two or three reasons they won't buy. Surface them and answer them. "Worried about lock-in? Export everything as Markdown anytime." "Too small a team? The free tier covers up to three projects." An unspoken objection is a silent exit; a spoken-and-answered one is a removed obstacle.
Final CTA. End with the same action you opened with, restated plainly, with no new information competing for attention. The reader who got this far is ready; don't make them scroll back up to find the button.
Notice that "how it works" comes after the problem, never before. Builders love to open with the mechanism because the mechanism is the part they're proud of. But the reader can't evaluate a solution to a problem they haven't agreed they have. State the problem first; let the reader nod; then show the fix.
Proof is the most powerful element on the page and the easiest to fake — which is exactly why you shouldn't. The reader's instinct for hollow proof is sharper than you think, and getting caught inflating it does more damage than having none. This connects directly to The Competence Tax: every embellishment the reader catches makes them re-examine everything else you've claimed, including the parts that are true.
Here's how to use each kind of proof without crossing the line.
Logos. Only show logos of companies that genuinely use the product. A wall of famous logos that turn out to be "companies whose employees once signed up for the free trial" is a trust grenade. If you have three real customers, show three. Three honest logos beat twenty borrowed ones.
Testimonials. Real name, real role, ideally a real photo or link. A quote attributed to "Sarah K., CTO" with no company and no face reads as invented, because half the time it is. A specific quote — "cut our docs maintenance from a day a week to zero" — beats a generic one — "great product, highly recommend" — because specificity is the fingerprint of a real human.
Numbers. Use real figures and frame them honestly. "2,400 teams" is fine if it's true. "Join thousands of happy developers" when you have forty users is the kind of claim that, once discovered, makes the reader assume everything else is inflated too.
Fake or padded social proof doesn't just risk getting caught — it actively cheapens the page. Stock-photo "customers", invented testimonials, and vanity metrics all read as the moves of someone who couldn't get the real thing. If you're early and don't have proof yet, lead with something concrete you can stand behind: an honest demo, a clear guarantee, a free tier, your own track record. Absence of proof is survivable. Discovered dishonesty is not.
When you genuinely don't have proof yet — and early on, you won't — substitute demonstration for endorsement. A short, real product demo is proof: it shows the thing works. A clear, specific guarantee is proof: it shows you'll stand behind it. A generous free tier is proof: it shows you're confident enough to let people try before they trust. None of these require borrowing credibility you haven't earned.
The reader's question under every claim is "says who?" — answer it with proof you'd be comfortable having fact-checked.
Walk a typical developer landing page and count the calls to action above the fold. You'll often find four: "Sign up," "Read docs," "View on GitHub," "Book a demo." All styled similarly, all competing. The visitor's brain, faced with four equal options, frequently picks the fifth: leave.
A landing page should have one primary action, and it should appear more than once — at the top, once or twice through the body, and at the end. Same words, same prominence, same destination. This is One Primary Action and One Loudest Thing working together on the surface where they matter most: the loudest element on every screenful should be the single thing you most want the visitor to do.
The secondary stuff still exists; it just gets quieter. Make "Read the docs" a plain text link, not a button. Put "View on GitHub" in the footer. The hierarchy should be visible at a glance — one element is obviously the main move, everything else recedes.
.btn-primary {
background: var(--accent);
color: #fff;
padding: 12px 24px;
font-weight: 600;
border-radius: 8px;
}
.link-secondary {
color: var(--text-muted);
text-decoration: underline;
background: none;
padding: 0;
}
One filled button. Everything else is a quiet link. The visitor never has to decide what the main action is, because you already decided for them.
Repeat that one CTA down the page, but don't vary the wording. "Generate my docs" at the top and "Start your free trial" in the middle and "Get started now" at the bottom feel like three different offers and quietly erode confidence. Pick one phrase — ideally one that names the outcome, per Label the Outcome — and use it every time. Consistency reads as certainty, and certainty converts.
Builders often agonize over the hero and then end the page with a thin footer and no closing action. The reader who scrolled all the way down is the most qualified visitor you have — they read the whole argument. Don't make them scroll back up to act. Put the same primary button right before the footer, every time.
Faced with four equal buttons, the visitor's brain frequently picks the fifth option: leave.
Clever is the enemy here. A surprising hover animation, a CTA that says something witty, a button that morphs — these feel like polish to the person who built them and read as friction to the person trying to get a job done. Clarity converts; cleverness mostly just delays the click or kills it.
Screenshot your landing page above the fold and show it to someone outside your field. If they can't tell you what it does and who it's for in one sentence, rewrite the headline and subhead until they can.
Take your current headline and ask "so the user can what?" until you reach a human result. Put that result in the h1. Move every tech-stack word out of the hero and into the "how it works" section below.
Delete any feature list, spec table, or screenshot carousel from the first screen. Leave exactly one headline, one subhead, one button, and one proof line. The features move below, reframed as solved problems.
Put a single honest signal near the hero — real logos, a real star count, or one specific named testimonial. If you have none, swap in a concrete demo, a guarantee, or a free tier instead. Nothing invented.
Choose one primary action and one phrase for it. Style it as the loudest element. Demote every other action to a quiet link. Repeat the same button at the top, mid-page, and right before the footer — same words every time.
Lay the page out as problem, then how it works, then proof, then objections, then final CTA. Make sure "how it works" comes after the problem, and that each objection a skeptic would raise gets named and answered.
You don't need tricks to convert. You need to say what it is, who it's for, why now — and then get out of the way of the click.