A small, honest guide to writing project descriptions people actually read

I've read a few hundred project pages by now, my own included, and most of them fail in the same quiet way: they describe what the thing is and forget to give anyone a reason to care.

This is a guide for fixing that. It's short on theory and long on the questions I actually ask myself. Steal whatever's useful.

Start by answering one question out loud

Before writing anything, finish this sentence as if a friend asked you over coffee:

"So basically I made a thing that..."

Whatever comes out of your mouth — that's your first line. The casual version is almost always clearer than the polished one you'd write at the keyboard. Write it down before your inner editor shows up.

The structure that keeps working

I use the same four beats every time. Not because it's clever, but because it's repeatable and you stop staring at a blank page.

1. The hook — one or two sentences, the coffee version from above.
2. The tension — what made this hard or interesting. No tension, no story.
3. The move — the key decision you made. Just one. Don't list ten.
4. The result — what changed, ideally with something concrete.

Here's the difference in practice.

Before:

A responsive e-commerce dashboard built with React and a component library, featuring analytics, inventory management, and a customizable theme system.

That's a feature list wearing a sentence's clothes. Now:

The client could see their sales but couldn't act on them — the numbers lived in one tool, the inventory in another. I built a single dashboard where a low-stock alert is one click away from a reorder. Support tickets about "where do I even change this" dropped to almost zero.

Same project. The second one has a person in it.

Small writing habits that punch above their weight

• Cut the first sentence. Seriously, after you write the description, delete the opening line and read it again. It's usually warm-up throat-clearing.
• One idea per paragraph. If a paragraph has two ideas, it has a hidden paragraph break in it.
• Use real numbers when you have them. "Faster" is a claim. "Cut the export step from six clicks to two" is evidence.
• Read it aloud. Anywhere you stumble, the reader stumbles too. This is the single highest-leverage edit and it costs ninety seconds.

A note on tools and tone

You don't need to list your stack like a résumé. If it matters, mention it in passing — "built it in Next.js because the SEO mattered" tells me why you chose it, which is the only interesting part. A bare tag soup of React TypeScript Figma Tailwind tells me nothing I couldn't guess.

And about tone: write like you'd explain it to a smart friend who doesn't do your job. Not dumbed down — just unguarded. The corporate voice ("leveraged a robust solution to drive engagement") is where personality goes to die.

One last thing

Good project writing isn't about being a good writer. It's about being willing to say the true thing instead of the impressive-sounding thing. Those are almost never the same sentence — and the true one is always more interesting.

Try the four beats on your next project. If you get stuck, go back to the coffee sentence. It's never let me down. 🙂