A portfolio is evidence that you can build things. Three small finished projects with clear explanations beat one ambitious half-built one.
What a portfolio is for#
It answers three questions for whoever is looking:
- Can this person actually build something that works?
- Can they explain what they built and why?
- Do they finish things?
Everything below serves those three questions.
How many projects#
Three or four is plenty. Beyond that, extra projects add very little and dilute the good ones.
A useful spread:
- Something visual — a page or app people can click. See the portfolio page project.
- Something practical — a script that solves a real annoyance. A file organiser is a good example.
- Something with data — reads a file or calls an API and does something with the result.
- Something personal — connected to a hobby or interest. These are the ones people ask about.
The README matters more than the code#
Most people will read your README and never open a source file. Ten minutes here is the highest-value ten minutes in the whole exercise.
# Project name
One sentence: what it does and who it is for.
## Screenshot
[a picture or short recording]
## What it does
- Three or four bullet points
## How to run it
git clone https://github.com/you/project.git
cd project
pip install -r requirements.txt
python app.py
## How it works
Two or three sentences on the structure.
## What I learned
The interesting part. What was harder than expected,
what you would do differently.
## Next steps
What you would add with more time.The “what I learned” section is the one experienced people actually read. It shows self-awareness, which matters more than the project being impressive.
Publishing it#
- Code → GitHub. See Git and GitHub explained.
- Web projects → GitHub Pages or Netlify, both free. A working link is worth far more than a repository.
- Your own page → one simple page linking to everything, with two sentences about you.
Pin your best three or four repositories on your GitHub profile so they appear at the top.
Commit history counts#
A project with one commit saying “initial commit” tells a different story to twenty commits with clear messages. The second shows how you work — incrementally, with intent. It costs nothing to commit as you go.
Writing about a project honestly#
Say what it is. “A to-do app I built while learning JavaScript, with local storage so tasks survive a refresh” is better than “a full-featured productivity platform”. Overclaiming is transparent and works against you; being early in your journey and clear about it does not.
If you have nothing yet#
Start with one project this week. Pick something small from beginner programming projects, finish it, write the README, push it. Then do it twice more. That is a portfolio.
Questions people ask#
Do I need a custom domain?
No. A GitHub Pages URL is completely fine. A domain is a small nice-to-have, not a requirement.
Should I include projects in different languages?
Depth beats breadth. Two or three solid projects in one language read better than five shallow ones across five languages.
What if my code is not very good?
Everyone’s early code is not very good. Shipping something that works and explaining what you would improve is a strength, not a weakness.
Should I contribute to open source?
It is valuable and it is not a prerequisite. Documentation fixes and small bug fixes are a realistic starting point once you are comfortable reading other people’s code.