These are opinions, not rules, from someone still working on their own portfolio. Take what's useful and ignore the rest.
I'll share what I've aimed for on my own site, what I think a visitor actually needs, and a simple structure for case studies that keeps you honest.
Start with the visitor, not yourself
Who looks at a student portfolio? Mostly:
- a recruiter or hiring manager giving it 60 seconds,
- an engineer who'll spend five minutes if something catches them,
- a fellow student looking for ideas.
Every choice should serve those people. The recruiter needs to understand quickly what you build and for whom. The engineer needs evidence of judgement: decisions, trade-offs, and what you'd change.
What to include
Fewer, deeper projects
A long list of tutorial clones says "I followed instructions." Three well-explained projects say "I can make decisions." I'd rather show six projects in depth than twenty in thumbnails.
Case studies, not just screenshots
A screenshot shows what a project looks like. A case study shows how you think. My case studies use a fixed structure:
- Role. Solo, or which part of a team project was mine.
- Context. Hackathon, personal project, dates.
- The problem. Why anyone would need this.
- The approach. What I built and the key idea.
- Decisions. A few choices, each with its reasoning.
- What broke. Real problems and how I fixed them.
- Limits. What isn't done, isn't measured, or isn't real yet.
Section 7 is the one that surprises people, and it's the one that builds the most trust. When a project says "Escrow and KYC are stubbed integrations" or "the AI review eval has not been run against a real API key", you can believe the rest of the page.
Credit teammates
For team projects, say so, name people, and say which part you built. Hiring managers can tell when a solo claim is really a team effort, and it counts against you.
What you'd change
Naming a limitation reads as maturity, not weakness.
A way to contact you that works
Sounds obvious. Test the link or form yourself.
What to skip
- Skill bars. "React 90%" means nothing. 90% of what?
- Projects you can't explain. If someone asks "why did you choose X?" and you don't know, the project hurts you.
- Loading screens that block content. (See Day 16: if you have an intro, make it skippable.)
- Walls of buzzwords. List technologies inside projects, where they have context.
- Fake testimonials or inflated numbers. They're easy to spot and costly if spotted.
Structure your data so the site stays honest
A practical technique: keep content out of components and in plain data files. On my site:
- one file for the site-wide facts (section order, location, career start year), which the navbar, footer and command palette all read from,
- one file each for projects, posts and certifications,
- a hand-curated changelog where I add an entry when something ships.
// one source of truth, read everywhere export const site = { name: 'Your Name', location: 'City, Country', // city + country only, no street address careerStartYear: 2023, }; The benefit is that a fact lives in one place. Change your location once and the navbar, footer and metadata all agree. Contradictory details across a site make a bad impression.
One test
Could a stranger understand in 30 seconds what you build and for whom?
Show your homepage to someone outside tech for half a minute, then ask them what you do. If they can't say, simplify the first screen.
A habit that helps
Every claim on the site should be checkable against the code. If it isn't true in the repo, it doesn't go on the page. That includes numbers (only publish figures you can verify), live links (make sure they work), and "deployed" claims (say clearly when a project runs locally only).
A privacy note
Think about what you're publishing. City and country is plenty for a location; a street address isn't needed. Be careful with phone numbers and anything that makes it easy to find where you live.
A starter checklist
- [ ] One-line "what I do" at the very top
- [ ] 3–6 projects, each with role, problem, approach, limits
- [ ] Teammates credited on team work
- [ ] Working contact method
- [ ] Mobile layout checked
- [ ] Contrast checked
- [ ] Every link clicked once
- [ ] Nothing claimed that the code doesn't support
A case study template you can copy
Fill in each heading in a sentence or two. Keep the total to a page.
# Project name: one-line promise **Role:** Solo / team of N. Which parts I built. **Context:** Personal project / hackathon / course. Dates. ## The problem Who has it, and why current options fail. ## The approach The key idea, in plain language. A small diagram if it helps. ## Decisions 1. Decision, and why. What I rejected. 2. ... 3. ... ## What broke - Problem -> fix - Problem -> fix ## Numbers (only verifiable ones) - what was measured, and how ## Limits - What's simulated, stubbed, untested or undeployed. ## Links Repo, live demo (if there is one), write-up. The most common mistake is skipping "what broke" and "limits". They are the two sections that make the other five believable.
Example one-liners for the top of a portfolio
Not mine, just shapes. Replace with your own facts.
- "I build full-stack web apps and AI features, mostly with TypeScript and Postgres."
- "Student developer focused on data-heavy products: I like schemas, queues and boring reliability."
- "Frontend-focused developer who cares about accessibility and performance."
Good one-liners name what you build, with what, and what you care about, in one breath.
Your first screen, tested
Open your portfolio on a phone and ask:
- Can I tell what this person does without scrolling?
- Is there one obvious next action (view projects, contact)?
- Does it load quickly on a mobile connection?
- Is text readable without zooming?
If any answer is no, fix that before anything else.
A note on screenshots and demos
- Real screenshots, not stock mock-ups.
- Short clips show motion and interaction better than stills.
- If there's no live demo, say why. "Runs locally; no live demo" is more credible than a broken link.
- Alt text for every image. It helps accessibility and describes your work for anyone who can't see it.
Keeping it fresh
A portfolio decays. A tiny routine:
- Monthly: check every link, update the project list.
- After shipping: add a changelog entry.
- Twice a year: re-read it as a stranger, and cut anything stale.
Quick quality checks
- [ ] Lighthouse or similar accessibility check
- [ ] Contrast checked on every colour pair
- [ ] Keyboard navigation works
- [ ] No console errors
- [ ] Open Graph image set, so shared links look good
- [ ] 404 page exists
- [ ] A sitemap and RSS if you write posts
What's the best portfolio you've seen, and why did it stick with you?
☕ Enjoyed this post? You can support my writing on Ko-fi.
