Skip to content
Velloreth
Projects 5 min read

Building a Portfolio Project That Gets Noticed

A portfolio project should show judgement, not just code. Learn what to build, what to document, and the mistakes that hide good work.

By

What a portfolio project is for

A portfolio project answers one question for a reviewer: can this person build something and make good decisions?

A tutorial clone does not answer it. It shows that you can follow instructions, which is a weaker signal than the ability to scope a problem.

The signal is judgement. The choice of what to build, what to leave out, and how to explain it.

What to build

Solve a problem you have. A tool you actually use is a project with real requirements, and the decisions are motivated.

Pick a scope you can finish. A finished small project beats an abandoned large one. A reviewer sees the finished state, not the ambition.

Choose something with a hard part. A project with a genuine constraint, such as offline support, a large dataset, or a real-time requirement, gives you something to explain.

Avoid the crowded ideas unless you have a different angle:

  • A to-do app
  • A weather app
  • A blog with no content
  • A clone of a popular product

A different angle is enough. A to-do app with offline sync and a documented conflict resolution strategy is a different project.

The README

The README is the first thing a reviewer reads, and it decides whether they read the code.

The sections:

# Project name

One sentence on what it does.

## Why

The problem it solves and why you built it.

## Demo

A live link and a screenshot.

## How to run it

The exact commands.

## Architecture

A short description and a diagram.

## Trade-offs

What you chose, what you gave up, and why.

## What I would do next

The known limitations and the next step.

The trade-offs section is the one that matters most. It shows that you considered alternatives, which is what a senior reviewer looks for.

A concrete trade-off:

I used a single Postgres table with a JSONB column instead of a normalized schema, because the shape changes often and the queries are simple. The cost is that a query on a nested field is slower, and I would normalize it if the read volume grew.

This is worth more than a feature list.

The code

A consistent structure. A reviewer navigates by convention, so a predictable layout helps.

A clear entry point. A main or an index that shows the flow.

A few tests around the core logic. Not full coverage, and enough to show the practice.

A linter and a formatter. A consistent style is a signal of care.

A CI workflow. A green check on the repository shows that the build is reproducible.

Comments that explain why, not what. The code says what.

No commented-out code. It is noise.

A .env.example rather than a committed secret.

The deployment

A live link removes the friction. A reviewer will not clone and run a project.

A free tier is enough. A static host, a small container, or a serverless function.

A seed script so the demo has data.

A demo account if the project needs a login.

A note on the cost if the demo may be taken down.

The presentation

A screenshot in the README. A reviewer may not click the link.

A short video for a project with an interaction that a screenshot cannot show.

A clear title. The repository name should say what the project is.

A description on the repository. It appears in a search result.

A pinned repository on the profile, so it is the first thing seen.

Choosing the scope

The hardest decision in a portfolio project is what to leave out. A project that tries to do everything is a project that is 60% done, and a reviewer sees the unfinished parts. The way to scope it is to write the one-sentence description first, and then to ask of every feature whether the sentence is still true without it. A feature that the sentence does not need is a feature for the next version. The second technique is to pick one hard part and to do it well, rather than five easy parts. A project with a genuine constraint, such as offline support or a large dataset, gives you something to explain in an interview, and the explanation is what the reviewer is looking for. The third is to set a deadline and to ship at it, because a project that is always two weeks from finished is a project that never demonstrates anything.

The interview angle

A portfolio project is often discussed in an interview, and the discussion is where the value is realised. The questions a reviewer asks are about the decisions: why this database, why this structure, what would you change at ten times the traffic. A project with a documented trade-off gives you a prepared answer, and a project without one gives you a blank. The second angle is the failure: a project that had a real problem and a fix is a project with a story, and a story is memorable. The third is the scope: being able to say what you deliberately left out shows judgement, which is the quality the project is meant to demonstrate. Preparing those three answers before an interview turns a repository into a conversation.

What to avoid

A project that is a list of features with no explanation. The reviewer cannot tell what you decided.

A repository with no README. The reviewer has to read the code to understand the purpose.

A project that does not run. A broken build is a strong negative signal.

A committed secret. It is a security signal as well as a care signal.

A large project that is 20% done. The unfinished parts are what the reviewer sees.

A clone with a new name. It is recognisable.

A project with no tests and no CI. It is not disqualifying, and it is a missed opportunity.

A README that is a wall of text. Use headings and short paragraphs.

A quotable summary

A portfolio project shows judgement, which a tutorial clone does not. Build something you actually need, scope it so you can finish it, deploy it, and write a README that explains the problem, the architecture and the trade-offs. Two or three finished projects with a clear explanation beat ten abandoned repositories, and the trade-offs section is the part a reviewer values most.

For the writing, see write-a-good-readme and asking-good-technical-questions. For the broader context, debugging-strategies-that-work and avoiding-developer-burnout.

Frequently asked questions

What makes a good portfolio project?
It solves a real problem, it is finished and deployed, and the README explains the decisions and the trade-offs. It shows that you can scope a problem, choose a solution, and ship it. A clone of a tutorial shows that you can follow instructions, which is a weaker signal.
How many portfolio projects should I have?
Two or three strong ones are better than ten weak ones. A reviewer spends a few minutes on a portfolio, so the first project must be the best. A single project that is finished, deployed and well documented is a stronger signal than a list of repositories.
Should I build a to-do app?
Only if it does something a to-do app does not. A to-do app is the most common portfolio project, so it does not differentiate. A to-do app with offline sync, a conflict resolution strategy and a documented trade-off is a different project from a to-do app that stores a list in local storage.
What should the README contain?
What the project does, why it exists, a screenshot or a link, how to run it, the architecture, the trade-offs, and what you would do next. The trade-offs section is the one that most projects omit and the one a reviewer values most.
Do I need tests in a portfolio project?
A small test suite is a strong signal, because it shows that you think about correctness and that you can write a test. It does not need full coverage. A few tests around the core logic are enough to demonstrate the practice.
Should I deploy my portfolio project?
Yes. A live link removes the friction of running it locally, and it shows that you can deploy. A project that only runs on your machine is a project a reviewer may never see.