How to write a listing that gets upvotes

A listing on a ranked board is a card in a list of forty cards. It has a logo, a name, a line of text, and a vote count. Someone is scrolling. You get about two seconds.

Almost everything that determines whether they stop is the one line of text. Everything else — the description, the screenshots, the first comment — matters only for people who already stopped. So the ordering of effort is not obvious from the ordering of the form.

The tagline is the whole job

Sixty characters, give or take. It has to answer one question: what does this do for me?

The failure mode is describing the category instead of the job. Compare:

The right-hand column is not more clever. It is more specific. A reader can tell in two seconds whether it applies to them, and that is the only decision the tagline needs to produce.

Three rules that survive most cases:

Lead with the verb. "Turns", "deploys", "files", "finds". A tagline that opens with "A platform for" has spent its first three words on nothing.

Name the input and the output. The pairing is what makes a tagline concrete. Meeting notes → draft. Pull request → preview environment. If you cannot state your input and output, you may not be finished deciding what the product is.

Delete "AI-powered". On an AI tool directory, every listing is AI-powered. It is not a differentiator, it is the room you are standing in. Those eleven characters are better spent on what the AI actually does.

A useful test: read your tagline to someone who has never seen the product and ask them to describe who it is for. If they can, it works. If they ask a clarifying question, the answer to that question probably belongs in the tagline.

The description is for people who already stopped

Six hundred characters or so, and its job is different: it converts interest into a click. Someone read the tagline, thought "maybe", and wants to know if it is real.

Structure that works:

1. One sentence expanding the tagline — the same claim with the mechanism attached. How does it do the thing?
2. Two or three sentences of specifics — what it integrates with, what it supports, what the limits are.
3. One sentence on who it is for — and, if you are confident, who it is not for.

That last one is underused. "Built for teams already using Linear and Slack" excludes people, which feels like it costs you something. It does not. It costs you clicks from people who would have bounced, and it earns you trust from the people who match, because you have just demonstrated that you know who you are talking to.

Things to cut without reading twice: "seamlessly", "revolutionary", "cutting-edge", "leverage", "in today's fast-paced world", and any sentence about how the industry is changing. Nobody reading a directory card needs the industry explained to them.

Write the description in the same voice you would use to explain the product to a colleague. If a sentence would be strange to say out loud, it is strange to read.

Screenshots do more than you think

Most people look at the image before they read anything. Two rules:

Show the product working, not empty. An empty dashboard with an onboarding modal over it is the state you want users to leave, not the one you want to advertise. Populate it. Fake data is fine as long as it is plausible — nobody is fooled by "Lorem ipsum Corp" but nobody minds "Acme Ltd" either.

Crop to what matters. A full-page capture at browser width shrinks your interface to an unreadable smear in a card. Crop to the part of the screen that demonstrates the claim in your tagline.

If the directory takes multiple screenshots, order them as a sequence: the thing you do, then the result. Not five views of the same settings page.

The first comment

Some directories let you post an opening comment on your own listing. It is the most-read piece of text you will write, and it is usually wasted on a restatement of the description.

Write about why the thing exists. Not the market opportunity — the specific annoyance that made you build it. What did you try first that did not work. What is still bad about it.

That last one is the one people skip, and it is the one that earns votes. A maker who says "the export is slow above 10,000 rows and I am working on it" reads as a person with a real product. A maker who lists five bullet points of benefits reads as a landing page with a face on it.

Two hundred words is plenty. End with a question you actually want answered — a real one, not "let me know what you think". "Does anyone have a workflow for X that already works? I would rather use it than keep building this" gets replies.

Then reply to every comment. On most ranked surfaces, the first few hours determine whether anyone else sees the listing at all, and a thread with the maker in it is what makes people stay.

The thing that does not work

Asking for votes. Every ranked platform detects coordinated voting, and the ones that do not are not worth ranking on anyway. Telling people you launched is fine — sending them a link and letting them decide is fine. Sending twenty colleagues a message that says "upvote me" is how listings get removed.

The upvote is a lagging indicator. What you are actually optimising is whether a stranger, scrolling, stops. Get the tagline right and the rest is downstream.

Before you submit

Read your own listing on your phone, in a list of other listings, with fresh eyes. Our directory of tools is a reasonable place to do it — scroll it, then find your own card and see whether it survives the comparison.

When it does, submit it. And if you want the form filled in for you first, our audit reads your page and drafts the whole thing, which is usually a better starting point than a blank field.