Build a developer portfolio that shows judgement

A portfolio asks someone to spend attention on your work. Help them understand why the project exists, what you contributed, and which decisions are worth inspecting. The answer is rarely to add another service merely to make the architecture diagram larger.

Decide what the project should demonstrate

Choose a capability before choosing a project. You might want to show how you clarify ambiguous behaviour, test a boundary, explain a trade-off, or maintain a small feature after feedback. Those goals suggest different projects and different evidence.

MIT’s career toolkit on relevant experience includes personal projects among possible sources of evidence. It does not make public side projects mandatory. Scott H. Young’s Get Better at Anything, consulted through its Blinkist summary, also prompted the distinction between completing an exercise and demonstrating what you learned from it.

For an experienced developer, a permitted written account of a decision may be more relevant than another sample application. For someone entering the field, a small original extension to a tutorial may be enough to create a useful discussion. The important word is original: make clear which work was provided and which decisions were yours.

Try the decision

A developer can publish a small project, but not employer code. What should the portfolio show?

Publish screenshots and call the project production-readyExplain a decision, test and known limit in a shareable project

Appearance alone does not reveal decisions, checks or remaining limits.

Next step: Use only work you have permission to share.

This is an illustrative decision with stated assumptions. It cannot establish your employer’s policy or predict an individual career outcome.

Make one decision inspectable

Consider an illustrative booking demo. A generic portfolio description says it uses a frontend framework, a backend framework, and a database. A more useful account explains one constraint: a user should not be told a booking succeeded if the requested slot is no longer available.

The project note can describe the behaviour you chose, the alternatives you considered, and the checks you implemented. It should also state what you did not test. A simple demonstration may not establish that the design works correctly under concurrent requests or realistic failure conditions.

That limitation is not something to hide. It creates an honest boundary and a meaningful next question. “This demo tests the basic workflow but not concurrent contention” is a more useful statement than “production-ready booking platform” without the supporting work.

The example is about presenting evidence, not prescribing a booking-system architecture. Use a short decision document to make the reasoning inspectable, and choose technical sources appropriate to the actual implementation before making correctness claims.

Give the reviewer a short route through the work

Start the README with the problem, the intended user, and the project’s current scope. Then point to one meaningful decision and one meaningful check. Include setup instructions that you have actually tried in the stated environment, or clearly mark them as unverified.

A reviewer should not need to explore every directory to learn what matters. Link directly to the relevant test or design note. Explain where generated code, starter templates, libraries, or external assets were used. Respect their licences and do not imply that their work is yours.

A brief case study can answer: what was uncertain, what you chose, why you chose it, how you checked it, and what remains. A diagram is useful only if it explains something those sentences cannot make clear. Decorative complexity is not evidence of deeper engineering.

Keep claims consistent across the README, CV, and interview account. Evidence-based CV writing helps make the short claim match the work a reviewer can actually inspect.

Distinguish a demonstration from production readiness

A working demo does not establish secure operation, recoverability, accessibility, scale, or long-term maintenance. State which of those concerns you addressed and how, rather than adding an all-purpose disclaimer after making sweeping claims.

Do not use real customer data or secrets to make a demo look authentic. Use synthetic data and safe defaults. If you host the project publicly, consider its exposure and ongoing maintenance rather than treating deployment as a one-time portfolio checkbox.

When AI tools contribute, describe the contribution where it is relevant to evaluating your work. You should be able to explain the important code and decisions you present as evidence of your capability. A large generated codebase that you cannot evaluate does not demonstrate ownership.

The guide to end-to-end ownership shows how much sits beyond implementation. Your portfolio need not cover every stage, but it should not claim the stages it has not covered.

Respect time, ownership, and other ways to show skill

Set a boundary for the project. A portfolio can become endless unpaid work if every application seems to require another feature. Stop when the intended capability is inspectable, and improve it only when you have a clear reason.

Never publish employer code, internal documents, private incidents, or confidential data without the necessary permission. An anonymised name does not automatically make the underlying material yours to share. A synthetic example can demonstrate the same reasoning without exposing someone else’s information.

People have different amounts of spare time and different restrictions on public work. A missing portfolio is not evidence of weak skill. The purpose of a portfolio, when useful and feasible, is to support a conversation about your judgement. A clear account of real work can support that conversation too.

For the surrounding career decisions, use the developer career reading guide. It connects portfolio work to choosing a direction, building skills, preparing applications, and setting sustainable ambitions.