Your Portfolio Should Explain Decisions, Not Display Screenshots

Your Portfolio Should Explain Decisions, Not Display Screenshots

A polished screenshot can show that an application has a dashboard. A list of badges can show that its repository contains Kotlin, React, PostgreSQL, or whatever else was used that week.

Neither tells me why the software is built that way.

What problem did the project solve? Which constraint changed the design? What did you deliberately leave out? Which alternative looked attractive but failed under the real requirements? How did you verify that the result worked?

Those questions reveal engineering judgment. That is what a useful developer portfolio should make visible.

Screenshots and technology lists still have a place, but they should support the story. They should not be the story.

Consider this project description:

Task manager built with Kotlin Multiplatform, Room, Ktor, Jetpack Compose, SwiftUI, Clean Architecture, and MVVM.

It tells us which nouns appeared in the repository. It does not tell us whether Kotlin Multiplatform was a good boundary, whether offline writes were safe, or whether the architecture solved a real problem.

A more useful description would be:

The application had to accept task updates during unreliable connectivity on Android and iOS. I kept Room as the local source of truth, queued writes in an outbox, and used Ktor for synchronization. I shared persistence and conflict rules, but kept Compose and SwiftUI native because the two apps had different navigation and lifecycle needs.

The second version names fewer technologies, but it gives the reader much more to evaluate:

• the operating constraint;
• the chosen boundary;
• the reason behind it;
• the cost of the decision;
• and the behavior the implementation must prove.

That is the difference between presenting a stack and presenting engineering.

Your portfolio is not an archive of everything you have ever pushed.

GitHub's current portfolio guidance recommends highlighting three to five projects that are relevant to the work you want and that demonstrate different skills. I like that range because it forces selection. Five case studies with distinct signals are more useful than twenty cards that all say “built with React.”

Choose projects that give the reader different reasons to trust you:

• Product feature: Translating an ambiguous need into a bounded solution
• Reliability work: Failure handling, tests, observability, and recovery
• Migration or refactor: Working inside constraints without rewriting everything
• Performance improvement: Measurement, bottleneck analysis, and explicit trade-offs
• Collaboration or open source: Communication, review, issue handling, and maintainership

You do not need one project in every row. You do need to avoid showing the same project five times with different color palettes.

Relevance also matters. If you want backend platform work, a small service with careful failure handling may say more than a visually impressive landing page. If you want Android work, show a project that deals with lifecycle, persistence, accessibility, or testing—not only a collection of composables.

A project page should let a technical reader understand the work in a few minutes, then go deeper if they want to inspect the repository.

A practical structure is:

## Project name

### Problem
Who had the problem, and what behavior needed to change?

### Constraints
What limited the solution: time, privacy, compatibility, offline use,
team ownership, deployment risk, device support, or legacy code?

### Decision
What did you choose, and why did it fit those constraints?

### Rejected alternatives
Which serious options did you consider, and why were they weaker here?

### Implementation
What are the important boundaries, data flows, and failure paths?

### Evidence
Which tests, diagrams, commands, releases, or observable behaviors
support the claims?

### Outcome and lessons
What changed, what remains limited, and what would you do differently?

This is not a demand for a long essay about every weekend experiment. A small project may need only a concise README. A deeper system may deserve a dedicated page or article.

The structure matters more than the length. It forces you to connect the problem to the implementation instead of jumping from a product sentence directly to screenshots.

GitHub's README guidance describes the README as the place to explain what a project does, why it is useful, how to get started, where to get help, and who maintains it. For a portfolio repository, I would add one more responsibility: explain the decisions that a code browser cannot infer.

“I chose PostgreSQL because it is powerful” is not a decision. It is a compliment.

A decision becomes useful when it is attached to a constraint:

• “We needed transactional updates across these three records.”
• “The application had to run on devices without a reliable connection.”
• “The team could not operate another distributed data store.”
• “The migration had to preserve the existing API for older clients.”
• “The first release had two weeks, so we postponed multi-region failover.”

Constraints explain why a reasonable engineer might choose one design over another. They also protect the case study from becoming architecture theatre. The most impressive decision is often the one that keeps the system smaller.

Be specific, but do not invent precision. If you did not measure peak requests per second, do not add a suspiciously neat number later. Say that traffic was modest and the main constraint was operational simplicity. Honest uncertainty is better evidence than manufactured scale.

Many portfolios describe the winning approach as if it were obvious from the beginning. Real engineering rarely works that way.

Suppose you kept native Compose and SwiftUI screens in a Kotlin Multiplatform project. The interesting part is not only that the UI stayed native. It is that you considered a shared UI and decided the extra reuse did not justify the navigation, lifecycle, or design-system compromises for that project.

That tells the reader three things:

1. You knew another option existed.
2. You evaluated it against the actual constraints.
3. You understood what your chosen approach would cost.

Do not create a fake tournament with ten alternatives. Include the one or two options a thoughtful reviewer would naturally ask about.

My Architecture Patterns overview discusses how patterns organize responsibilities. In a portfolio, naming the pattern is only the start. Explain which responsibility needed a boundary and what would become harder if that boundary moved.

A screenshot proves that one screen existed at one moment. Useful evidence goes further.

Think of it as a ladder:

1. Claim: “The project works offline.”
2. Artifact: an architecture diagram and an outbox table in the schema.
3. Reproducible check: tests covering queued writes, retry, and reconciliation.
4. Observable outcome: a short demo showing a write made offline and synchronized after reconnection.

Not every project needs all four levels. Important claims should have more than prose behind them.

Good evidence can include:

• a small architecture diagram that matches the code;
• a documented setup path that another developer can follow;
• focused unit, integration, or UI tests;
• a continuous-integration workflow with inspectable runs;
• an Architecture Decision Record for a consequential choice;
• release notes or a working deployment;
• before-and-after measurements when performance was the problem;
• an issue or pull request that shows collaboration and review.

The repository should expose a short verification path when practical:

git clone https://github.com/you/project.git
cd project
./gradlew test

Replace that example with the real commands for your project, including any required environment setup. A command that only works on your laptop is not useful documentation.

GitHub supports workflow status badges, and a passing badge can be a helpful entry point to the latest run. It is not a certificate of quality. A green workflow may run one trivial test, so let readers inspect what the workflow actually verifies.

This is the same principle I use in Claude Code Meets Android CLI: Build, Run, and Test: code-level confidence, UI evidence, and a user flow answer different questions. One green check should not pretend to answer all of them.

Screenshots are useful when visual behavior matters. Use them to show a responsive layout, an accessibility state, a data visualization, or a difficult interaction.

Then add context:

• What should the reader notice?
• Which constraint shaped the screen?
• Was this the final state or a prototype?
• What behavior cannot be seen in the image?

A caption such as “The empty state keeps the primary action visible and explains why no results exist” teaches more than “Dashboard screenshot.”

For a backend service, a sequence diagram, trace, or failure-recovery timeline may be more honest than a decorative admin screen. Match the evidence to the engineering claim.

Some of your best engineering decisions may belong to an employer or client. That does not give you permission to publish their code, data, architecture, customer names, incident details, or internal metrics.

Start with your employment agreement, client contract, and company policy. When the boundary is unclear, ask the owner of the work before publishing anything.

You can often describe the judgment without exposing the asset:

• explain the class of problem instead of naming the company;
• rebuild a small example with dummy data and a different domain;
• draw a simplified architecture that omits sensitive topology;
• describe your responsibility and decision process without claiming sole ownership;
• state outcomes qualitatively when exact metrics are confidential;
• link to public releases, talks, or documentation the organization already approved.

Private activity can still provide a limited signal. GitHub allows you to show anonymized private contribution counts without revealing repository details. Treat that as supporting context, not proof of what the work contained.

Before making any repository public, review its entire history—not only the latest files. GitHub's guidance on removing sensitive data warns that rewriting history has side effects and that exposed credentials should first be revoked or rotated. Push protection and secret scanning help, but they do not replace a deliberate privacy review.

Personal branding becomes noisy when every platform contains a slightly different identity. Give each surface a job instead.

• Your website holds the durable case studies and longer technical articles.
• GitHub holds the code, README, issues, releases, and reproducible evidence.
• LinkedIn introduces the lesson, the decision, or the discussion to a professional audience.
• Your resume points to the two or three pieces most relevant to a specific role.

The content should connect, not duplicate blindly. A LinkedIn edition can open with the professional tension behind a project, then link to the full case study. The case study can link to the repository and to a deeper article about one architectural choice. The repository can link back to the stable project page.

GitHub's profile guidance recommends adding a professional bio, a profile README, a portfolio or website link, and relevant social links. Use that space as a map. Do not make a visitor search five platforms to understand what you do.

Numbers are valuable when you know how they were measured.

“Reduced cold start from 2.4 seconds to 1.3 seconds on a Pixel 8 using a defined benchmark” is evidence if you can explain the setup. “Improved performance by 80%” is noise if the baseline, device, build, and metric disappeared.

When you do not have a number, describe an observable result:

• the migration shipped without changing the public API;
• the new test reproduces a failure that previously escaped;
• another developer can run the project from the documented setup;
• an offline write survives process restart;
• the open-source change was reviewed and merged.

Do not turn every minor commit into a personal-brand announcement. Publish when you can teach a decision, a failure, a method, or a result. Consistency matters, but signal matters more than frequency.

You do not need a redesign project before improving the content. Spend one focused week on the evidence.

Write down the work you want next. Backend infrastructure, Android product engineering, developer tooling, and engineering leadership require different evidence.

Score each candidate for relevance, depth of judgment, available evidence, and what new signal it adds. Remove duplicates.

Use the problem, constraints, decision, alternatives, implementation, evidence, outcome, and lessons structure. Keep the opening readable by someone who has not seen the repository.

Improve the README, setup instructions, test command, architecture diagram, repository description, topics, and relevant links. Remove badges that do not help a reader evaluate the project.

Inspect the Git history for secrets and proprietary material. Verify every number and ownership claim. Replace confidential details with an approved abstraction or remove them.

Update your website, GitHub profile README, pinned projects, LinkedIn profile, and resume so they point to the same strongest work.

Give one case study to another developer. Ask them to answer four questions after five minutes:

1. What problem did this project solve?
2. Which constraint mattered most?
3. What decision did the developer make?
4. What evidence makes the result credible?

If the answers are unclear, another gradient background will not fix the portfolio. Rewrite the story.

A developer portfolio is not a museum of finished screens. It is a compact explanation of how you work when requirements are incomplete, constraints conflict, and several solutions look reasonable.

Show the interface when the interface matters. List the stack when it gives necessary context. Then spend most of the page on the decision: what you understood, what you chose, what you rejected, what you verified, and what you learned.

That is the part another engineer can discuss with you.

If someone opened your strongest project for five minutes, which decision would you want them to understand first?