A Portfolio That Shows Judgment, Not Only Output

Reviewers of portfolios usually spend a short time on each one. In that time they look for the same thing a hiring manager looks for in an interview: evidence that the person made sensible choices when the situation was not clear. A finished project shows what was built. It rarely shows why it was built that way, and the reasons are what make the work transferable to a team with its own constraints.

What a reviewer is reading for

A reviewer typically asks three questions of any entry. What problem was this solving, and for whom? What did the person decide along the way? How do they know it works? The first question is answered by a short statement of context. The second requires the portfolio to show decisions, which means showing the alternatives. The third needs a result that can be checked, even if the check is modest.

Notice what is missing from that list: the number of tools used, the length of the code, the polish of the interface. Those can support the story, but they cannot carry it. A reviewer who sees a polished dashboard with no account of its data sources learns very little about the person behind it.

Reviewers also notice what the entry leaves out on purpose, such as data that cannot be shared. Saying that the data is private, and describing its shape and size, is better than hiding the source entirely.

Write a decision record for small projects

A decision record is a short document, usually under a page, that captures one choice and the reasons for it. It does not need a formal template. Four headings are enough: the context, the decision, the alternatives considered and the consequences. Writing one for each meaningful choice in a small project takes perhaps twenty minutes and turns a repository into an argument a stranger can follow.

Suppose you built a tool that classifies support tickets. A decision record might state that you chose a simple keyword model over a hosted language model because the tickets came from a narrow domain, the labels were stable, and you needed predictable cost and fast responses. It would then say what you gave up: the simple model misses paraphrases, and you measured how often it did. That one record demonstrates more judgment than a paragraph describing the stack.

Show what you rejected

Rejected options are the most underused material in portfolios. People hide them because they feel like evidence of wasted effort. In practice they show the range of your thinking. If you tried a method that failed, say why it failed and what it taught you about the data. If you considered a more elaborate design and set it aside, say what it would have cost and what would have changed your mind. A reviewer who reads that section learns that you can stop, compare and commit, which is a skill teams need and rarely see written down.

Keep the number of entries small. Three projects, each with a clear decision record and an honest account of its limits, will serve a reviewer better than a long list of tutorials. Depth shows judgment. Breadth alone mostly shows that things were finished.

Trade-offs should be stated as trade-offs. Writing that a solution is fast is weaker than writing that it is fast for the common case, slower for the rare one, and that the rare case was accepted because it happens once a month and can be retried. Specific trade-offs are harder to fake and easier to discuss in an interview.

Structure one entry in four paragraphs

A portfolio entry can run to four short paragraphs without losing a reader. The first sets the problem and the user, in plain language and a sentence or two. The second describes the approach and its most important decision, with the reason. The third covers what you tried that did not work and what you changed as a result. The fourth states the result and how you checked it, including the limit of that check. A link to the code or a sample output can sit beside the text, though most reviewers read the text first.

Keep the entry honest about scale. A project built over a weekend to test an idea should be described as that. Overstated scope is noticed quickly, and it damages the parts of the entry that were good.

The repository is part of the entry too. A reviewer who opens it will look first at the readme, then at the folder structure, then at whether the code runs. A short setup section and one command that reproduces the main result answer most of their questions before they ask them.

Practice the record on something you finished

Choose one small project you have already completed. Write a decision record for its three most important choices, using the four headings. Then rewrite the portfolio entry in four paragraphs. Ask someone who has reviewed technical work to read it and to tell you one thing they now know about how you think. If they cannot answer, the entry is still describing output. Revise until the answer comes easily, and until the rejected options are visible enough that a reader could work through the same decisions and reach the same place.

Keep the decision records in the repository, next to the code they describe, so that a reviewer who reads the code also reads the reasons. A record that drifts away from the code is worse than none, so update it when the decision changes.