I spent the last few months looking at developer portfolios more closely than anyone should reasonably want to.

I was building a tool that helps developers create and maintain portfolio sites. To make decisions about it, I read through hundreds of real portfolio pages, talked to developers about why they made the choices they made, and read everything I could find about how recruiters and hiring managers actually use these pages.

What I learned was not what I expected.

Most developer portfolios are not bad because the developer can't design. They're bad because they're answering the wrong question.

The developer thinks the portfolio is asking: "what can I do?"

The recruiter is actually asking: "can I trust this person to ship?"

Those are different questions and they need different answers. The portfolios that get developers hired answer the second one. Most portfolios I see are still trying to answer the first.

Here are the patterns I keep seeing, why they hurt, and what to do instead.…