Most portfolio projects fail before anyone reads a line of code. The recruiter opens the GitHub link, sees a default README, no live demo, and 40 commits all titled "update," and moves on. The screen is over in under a minute, and your project never got to make its case.
The fix is not more projects. It is one project built so the first 90 seconds of someone else's attention land where you want them. This guide walks through how to scope that project, document it so a reviewer can follow it cold, and ship it so it actually runs when clicked.
What a reviewer opens first, and in what order
When an engineer or recruiter clicks your repo, the open order is predictable: the live demo link (if there is one), the README, the file tree, then maybe one or two source files. They rarely clone and run anything. That order decides what you spend your time on.
A project that survives the screen treats those four surfaces as the product. The code matters, but the code is read last and skimmed, not studied. If your README is empty and your demo is a 404, the quality of your state management never gets evaluated.
That reframes the work. You are not only building software. You are building a short, honest case that you can scope a problem, finish it, and explain it. Three things every reviewer is quietly checking:
- Can this person define a problem and solve exactly that, without scope creep?
- Does the project run, today, without me debugging your environment?
- Can I understand what they built and why in two minutes?
Miss any one and the others stop counting.
A pile of half-finished tutorials hurts you more than a single small project that works. Reviewers read three abandoned repos as "starts things, doesn't finish." Pin one project that is genuinely done and archive or unpin the rest.
Scope one project that answers the three questions
The most common failure is ambition. "A full social network" or "an AI agent platform" reads as a project that will never be finished, and the half-built version proves it. Pick a problem small enough to actually complete and specific enough to be memorable.
A good test: you can describe the project in one sentence that names a real user and a real outcome. "A CLI that finds unused dependencies in a Node project and tells you how much install size you'd save" beats "a developer productivity suite." The first is finishable in a weekend or two and demos in ten seconds. The second never ships.
Go for depth on a narrow surface over breadth. One feature that handles its edge cases — empty input, network failure, malformed data — signals more engineering maturity than ten features that each work only on the happy path. Reviewers notice error handling because it is the part most candidates skip.
When you pick the stack, match it to roles you actually want. If the jobs you're targeting list TypeScript and Postgres, a Python-and-MongoDB project is a weaker signal even if it's better built. The project is a sample of the work you want to be hired to do.
If you use an AI editor to move faster, keep your judgment in the loop. Reviewers can usually tell when a project was generated wholesale and never understood — the giveaway is a candidate who can't explain their own architectural choices in a follow-up call. Use the tool to remove drudgery, not to outsource the decisions you'll be asked about.
Make the README the strongest file in the repo
The README is the screen. Treat it as the landing page for the project, because that's how it's read. A reviewer should understand what the project does, see it working, and know how to run it — all without scrolling past the fold of attention.
A README that survives the screen has, in order:
- One sentence stating what it does and for whom, above everything else.
- A demo — a live link, or a short GIF/screenshot embedded right at the top. Visual proof that it runs beats any paragraph.
- Why it exists — two or three lines on the problem and the one interesting decision you made (a tradeoff, a constraint, something you'd defend).
- How to run it — exact commands that work on a clean machine. Test them by cloning into a fresh directory.
- What you'd do next — a short, honest list of known limitations. This reads as engineering maturity, not weakness.
Keep a tight commit history too. Squash the "wip" and "fix typo" noise into meaningful commits. A reviewer who opens your history should see a story of deliberate changes, not a keystroke log.
If you want a place to draft the project's decisions and tradeoffs before they become README prose, a single working doc helps. Some developers keep a short decision log — what they chose, what they rejected, and why — which doubles as interview prep when someone asks "why did you build it this way?"
Ship it so it runs when clicked
A project that only runs on your laptop is, to a reviewer, a project that does not run. The single highest-leverage step after finishing the code is deploying it somewhere a stranger can click.
For a frontend or full-stack app, that means a live URL on a platform with a free tier. For a CLI or library, it means a clear install path and, ideally, a published package. For a backend API, a hosted endpoint with example requests in the README. Whatever the shape, the goal is the same: remove every step between the reviewer's curiosity and seeing it work.
Then check it from outside your own setup. Open the demo in a private browser window with no extensions and no cached login. Clone the repo into a clean folder and run your own setup instructions verbatim. The number of "finished" projects that fail this test — missing environment variable, hardcoded localhost, an unlisted dependency — is the reason this step is worth a full evening.
Before you share the link anywhere, hand the repo and live demo to one person who has never seen it and ask them to describe what it does after two minutes. If their summary matches your one-sentence pitch, the project survives the screen. If it doesn't, fix the README before you fix anything else.
Originally published at pickuma.com. Subscribe to the RSS or follow @pickuma.bsky.social for new reviews.
Top comments (0)