What to Include in a Developer Portfolio: A Recruiter-Readable Checklist

A developer portfolio is not a gallery of screenshots or a second CV. It is a short path from “this is what I do” to “here is proof” to “here is how you may contact me”. Use this checklist to make that path obvious.

A portfolio has one job

A developer portfolio is not a gallery of screenshots, a dump of every repository you have touched, or a prettier copy of your CV. Its job is to help a relevant person understand your professional direction and trust the evidence behind it.

The useful path is short:

1. Positioning: what kind of developer are you and what work do you want to do?
2. Proof: what have you built, changed, operated, or learned from?
3. Next step: how can the right person contact you, and under what conditions?

Most portfolio advice starts with templates, animations, or a list of sections. Start with the decision a visitor is trying to make instead: Could this developer be relevant to the problem we need solved, and is it worth starting a conversation?

That framing also removes a common source of anxiety. You do not need a perfect personal website before you can be discoverable. You need a small, honest surface that makes your strongest signal easy to inspect.

The seven things to include

1. A specific positioning statement

Put one clear sentence near the top. It should name the kind of work you do, the problems or domain you understand, and—when useful—the kind of opportunity you want.

Backend engineer building reliable data and payment systems for European SaaS teams. Open to senior remote roles in CET-friendly timezones.

That sentence is more useful than “passionate full-stack developer” because it gives a recruiter or hiring manager a search vocabulary and a reason to continue. It also gives you a filter: if a role has nothing to do with the work you want, it is probably not a good fit.

Avoid turning the headline into a keyword list:

JavaScript · React · Node · Python · AWS · Docker · Git · Agile · problem solver

Technologies belong in context. A visitor needs to know what you use them to accomplish.

If your job title is unusual, translate it into the language people actually search for. “Product-minded systems builder” may describe you well, but “Staff backend engineer specialising in distributed systems” is easier to match to a real need.

2. A short “what I am looking for” section

A portfolio becomes more useful when it tells people what happens next. Add a compact section covering the preferences that affect whether a conversation makes sense:

• full-time, contract, freelance, or open to more than one;
• remote, hybrid, or on-site;
• preferred geography or timezone;
• availability or notice period, if you want to share it;
• domains or problem types that interest you;
• work you do not want.

This is not a demand for a rigid personal brand. It is practical routing information. “Open to work” alone tells a visitor very little. “Open to backend or platform roles, remote in European timezones, available from October” is actionable.

Do not invent availability to look more attractive. If you are not looking, say so. A truthful “open to exceptional projects only” is a better signal than a permanently active badge that creates irrelevant contact.

3. Two or three projects with real context

The centre of the portfolio should be a small set of projects you can explain without rehearsing marketing copy. Professional work is ideal, but a personal project, open-source contribution, research project, or internal tool can also be strong evidence when you describe your role honestly.

For each project, answer these six questions:

1. What problem existed? Who needed what, and why did it matter?
2. What did you own? Separate your work from the team’s work.
3. What constraints shaped the solution? Mention scale, latency, budget, legacy code, deadlines, privacy, or a missing dependency when relevant.
4. What did you decide? Explain one or two meaningful technical choices and the alternatives you rejected.
5. What changed? Use a real outcome: latency, reliability, cost, adoption, workflow time, error rate, or a concrete user result.
6. What would you change now? A trade-off or limitation makes the case study more credible, not less.

A weak project entry says:

Task manager built with React and Firebase.

A stronger one says:

Built an offline-first task queue for field technicians working with intermittent connectivity. I owned the sync model and conflict handling, choosing an append-only local log over last-write-wins updates. The first version reduced duplicate submissions in our pilot; the remaining trade-off was higher storage complexity on older devices.

The second description gives someone a reason to ask a technical question. That is what a portfolio is for.

You do not need to publish confidential code or disclose a client’s private metrics. Replace sensitive numbers with honest ranges, describe the constraint without naming the customer, or show a redacted architecture diagram. Never turn a private employer project into public proof without permission.

4. A path to inspect the evidence

Every project should have the lightest useful next step:

• a live demo, if it is stable and safe to share;
• a repository, if the code is public and readable;
• a short technical write-up;
• screenshots or a two-minute walkthrough when a demo cannot be public;
• a pull request, issue, package, talk, or design document that shows your contribution.

Do not make a visitor register, download a strange file, or run the project locally just to understand what it does. Put the explanation before the link. A live demo that is broken is worse than no demo; remove it until you can repair it.

GitHub is excellent for the deeper inspection layer, but it is not automatically a complete portfolio. GitHub describes a personal profile as a place to showcase the work and contributions you choose to share, and its profile README and pinned items can orient visitors quickly. Use it as evidence, then add the context a repository page cannot provide. See the official GitHub profile documentation and the guide to managing a profile README.

5. Evidence that you can work with other people

A portfolio made only of solo screenshots leaves an important question unanswered: how do you behave in a real codebase with other constraints and contributors? Add one or two signals of collaboration when you have them:

• a pull request that was reviewed and merged;
• an open-source issue you investigated;
• documentation or tests that helped other users;
• a migration or incident you coordinated;
• a design decision that required alignment with product or operations;
• mentoring, technical writing, or a talk where you made a difficult idea clear.

The point is not to collect GitHub activity for its own sake. A thousand commits do not explain your judgement. One well-described contribution can. Explain the situation, your part, and what changed.

If you are early in your career, do not apologise for not having production scale. Show that you can finish something, read an existing codebase, respond to feedback, test your assumptions, and explain what you learned. Those are real signals.

6. A contact route with boundaries

Make it possible for a relevant person to reach you, but do not confuse maximum exposure with maximum opportunity. At minimum, state what kind of contact you accept and where it should go.

A raw personal email address in a public footer is simple, but it also makes scraping and unfiltered outreach simple. Alternatives include a contact form with spam protection, a professional address you monitor separately, or a profile link with clear preferences and an inbox you can triage.

Whatever route you choose, tell the sender what a useful first message contains. For example:

Please include the company, role, compensation range, location or timezone, and the technical problem. I am not taking generic agency introductions.

This is not being difficult. It saves both sides a low-value exchange. A controlled contact path also lets you be discoverable while deciding when you are actually available.

If you want a deeper look at the trade-off between visibility and inbox quality, read how to stop recruiter spam as a developer and how to create a developer profile link recruiters can actually use.

7. A visible update date

A portfolio is a product that decays. A project link breaks, your availability changes, and the stack you want to be known for moves. Add a small “updated” date or “currently” note, then review the page every few months and after a meaningful project.

The review does not need to become a content schedule. Check:

• Does the first sentence still describe me?
• Are the two strongest projects still the right two?
• Do the links work on a phone?
• Is my availability accurate?
• Does every public contact route still lead somewhere I monitor?

A short, current portfolio beats a comprehensive page that has been abandoned for two years.

What to leave out

Removing weak material is part of building the page. Be suspicious of:

• skill bars such as “Python: 87%” with no defined measurement;
• every tutorial clone you completed while learning;
• badges that take more space than the work they represent;
• a wall of logos without project context;
• stock photos of people typing;
• metrics you cannot verify or explain;
• private client details, copied code, or confidential screenshots;
• a “coming soon” section that has stayed empty;
• a contact link that opens a dead account or an unmonitored inbox.

A portfolio is not stronger because it is longer. It is stronger when every element helps a visitor form an accurate view of your work.

The two-minute portfolio audit

Open the page on your phone, in a private window, and pretend you found it through a search result. Set a timer for two minutes. Do not click every project. Ask:

At 15 seconds

Can I tell what this developer does, where they work, and what they are open to?

At 45 seconds

Can I identify one project that is relevant to a real engineering problem?

At 90 seconds

Can I see what this person personally owned, and can I reach the evidence without guessing?

At two minutes

Do I know whether contacting them would be welcome, useful, and appropriately specific?

If the answer is no, do not start by changing the colour palette. Rewrite the top sentence, remove one weak project, add the missing context, or fix the next step.

A simple structure you can copy

Name
Backend engineer building reliable systems for [domain or type of team].

Currently
[What I am working on] · [availability] · [timezone or location]

Selected work
1. [Project] — [problem and outcome]
   My role: [what I owned]
   Decisions: [important trade-off]
   Evidence: [demo / repo / write-up]

2. [Project] — [problem and outcome]
   My role: [what I owned]
   Decisions: [important trade-off]
   Evidence: [demo / repo / write-up]

How I work
[One collaboration, open-source, writing, or operating signal]

Contact
[What a useful message should include] · [controlled contact link]

Updated [month year]

You can publish that structure on a custom website, a GitHub profile README, or a developer profile platform. The medium matters less than the clarity of the evidence and the honesty of the boundaries.

The thesis

A portfolio should not try to convince everyone that you are good at everything. It should help the right person recognise a relevant pattern quickly: this developer understands a problem we have, has evidence of doing similar work, and has made it clear whether a conversation makes sense.

That is also why a public developer profile and a portfolio serve different purposes. The portfolio explains your work. The profile can add availability, preferences, and a controlled contact rule. Together, they make discovery less dependent on a recruiter guessing your email address or a developer answering every message just to find one worthwhile opportunity.

For Google’s guidance on people-first content, the useful standard is simple: create something a reader would bookmark because it answers the real question completely, not a page assembled only to capture a search query. Apply the same standard to your own portfolio. Build for the person who needs to decide, not for an imaginary score.

If your portfolio needs a controlled way for relevant people to reach you, see how Reachdev works for developers.