GitHub README profile vs a portfolio page: what recruiters actually click

4 min read

A good GitHub profile README is a flex. Pinned repos, a couple of badges, maybe a stats card. Other developers get it instantly. But when a recruiter clicks through, they land on a code-shaped page that assumes they read commit history for fun. Most of them do not.

What a README is good at

Signaling to other developers, surfacing your pinned repos, showing a bit of personality. It works for the GitHub crowd. Keep it.

Where it falls short as a portfolio

No screenshots of the actual product, no plain-English description, no path for someone who does not read code. A recruiter or a non-technical founder wants to see what you built and what it looks like, not parse a list of repo names.

You probably want both

README for the developers who land on your GitHub. A portfolio page for the link you actually send people. The portfolio pulls your repos in and adds the screenshots and sentences a README cannot show. You can have it live without touching GitHub Pages.

The one-link test

If someone asks where they can see your work, the answer should be one link that makes sense to anyone. Not 'go to my GitHub and click around.' One link, readable by a human, pointing at the work.