What evidence belongs in a software engineering portfolio?

Show work a reader can understand and examine

Choose work that helps a reader understand a relevant engineering problem, your contribution and the evidence behind your decisions. There is no universal rule that every engineer needs a public portfolio. Follow the application’s instructions, and use a portfolio when it can add useful detail to your experience.

GitHub recommends highlighting relevant projects and making them easy to explore. Its guidance includes a helpful README, a demo where available, setup information and testing instructions. Those are useful ways to reduce the work a reader must do before they can assess the project.

Build a project account around one hard decision

Try this editorial structure: explain the problem and constraints, identify your responsibility, describe a decision and its alternatives, then show what you observed. Link the most useful evidence directly. Distinguish what you measured from what you expected to happen.

A search project might explain why you chose a simple index before a more elaborate retrieval system. A migration story might show how you checked compatibility and prepared a rollback. A frontend project might compare keyboard behavior before and after a change. Choose the decision that reveals how you work.

• Context: who needed the work, and what constrained it?
• Ownership: which part did you build or decide, and who else contributed?
• Decision: what alternatives did you consider?
• Evidence: what code, test, design note, demonstration or measured result can you share?
• Limits: what remains incomplete, unmeasured or outside your responsibility?

Make the repository useful without a guided tour

GitHub describes a README as a place to explain what a project does, why it is useful and how to use it. Add the context that the code alone cannot provide. Check the instructions from a fresh setup, and label dependencies that need an account or a paid service.

Our suggested review adds a few practical checks: can a reader find the relevant implementation, understand the test command and see the expected output? If the demo no longer runs, say so and provide an honest recording or example where you have permission. A broken link should not be the only route to understanding the work.

Describe outcomes without manufacturing numbers

A measured result needs enough context to interpret it. State what was measured, how it was measured and the conditions that limit the result. If you do not have a reliable metric, describe a concrete change and the evidence you do have.

Respect the limits of what you can share

Employer code and customer information may be confidential. Confirm permission before publishing work, screenshots or data. Where disclosure is limited, consider an approved high-level account, a clearly labeled independent example, or a discussion of your responsibilities that stays within those limits.

End with a useful next step: a relevant code path, a short demo, a design note or a contact route. Keep the website and résumé aligned so that the reader can follow the same account across both.