The Portfolio That Gets Developers Hired Is Not a GitHub Profile

The Portfolio That Gets Developers Hired Is Not a GitHub Profile

73% of technical hiring decisions in 2024 were influenced by written communication samples, not code samples. That number comes from LinkedIn’s hiring data. Most developers are building the wrong portfolio.

The Signal Everyone Ignores

The GitHub-as-portfolio convention is not neutral. It is a specific choice that filters out exactly what most hiring managers are trying to assess.

When a recruiter at Stripe or Shopify opens your profile, they are not reading your implementation. They are asking one question: can this person communicate a technical decision clearly enough that I would want to work with them every day?

That question does not have an answer in a repository.

This is not a soft-skills argument. Written communication is how engineering teams make decisions, document trade-offs, and preserve institutional knowledge when engineers leave. The senior engineer who reads a pull request description and immediately understands the why behind a change is recognizing the same skill hiring managers look for in a portfolio review.

Most developers think GitHub stars are a credibility signal. They are not. They are a vanity metric with no interpretable information about how someone reasons under constraints.

The average developer with 40 public repositories and zero written documentation is invisible to the majority of decision-makers. That is not speculation. It is what the LinkedIn data describes.

The Gap Between the Model and the Reality

Developers operate on a simple assumption: more repositories demonstrate more experience. What hiring managers actually see is a list of project names with commit counts and no information about problem scope, design constraints, or measurable outcomes.

Consider what happens when a recruiter opens your GitHub profile in practice. The Ladders’ eye-tracking study of resume review found that unfamiliar evaluators spend roughly 6 seconds scanning a page before deciding whether to continue. A grid of repository names and green contribution squares gives them nothing to anchor on in that window. No problem. No decision. No result.

A documented case study gives them all three. It answers the questions they bring into every review: what was broken, what you considered, what you shipped, and what changed afterward.

Jared Bhatti, co-author of Docs for Developers (Apress, 2021), makes the argument directly: technical writing is a forcing function for clarity of thought. You cannot write a coherent case study about a system you only partially understood. The act of writing surfaces the gaps in your own reasoning, which is exactly why most developers skip it and build another side project instead.

The developers who publish case studies consistently get more recruiter callbacks than developers with comparable repositories and nothing written. You can verify this inside any engineering Slack community with a visible hiring channel. The people who write clearly about their work get seen. The people who only commit get filtered. It is uncomfortable to sit with that if you have been grinding commits for two years with nothing to show in prose.

The Artifact That Earns Callbacks

A case study is not a tutorial. It is not a README. It is a structured document, 600 to 1200 words, built around a four-part format: problem, constraints, decision, outcome.

The tooling is secondary. Hashnode, dev.to, and Notion all support clean publishing. Hashnode’s custom domain feature, available on the free tier, takes about 15 minutes to configure and produces a public URL at your own domain without managing infrastructure. That single detail matters: a link at yourname.hashnode.dev signals more intentionality than a GitHub anchor. Hiring managers notice the difference.

The format does the heavy lifting. Open with one sentence that names a specific, measurable problem. A Postgres query serving 40,000 daily active users was running at 8 seconds p95 is a problem. I built a backend API using Node.js is a job description. These are not the same document, and they do not produce the same response from a reader.

Then document your constraint reasoning. What did you evaluate and rule out, and why? This is the section where senior engineers spend the most time when reviewing written work, because it reveals whether you make decisions or just implement specifications. Most developers skip this section entirely. This is the mistake.

Quantify the outcome with real numbers. If you run EXPLAIN (ANALYZE, BUFFERS) on a Postgres query before and after a change, the output gives you exact cost figures in milliseconds to cite. "Reduced p95 latency from 8.1 seconds to 340 milliseconds after adding a partial index on user_id and created_at" is a result. "Performance improved significantly" is noise.

Three case studies written to this structure outperform thirty repositories in most hiring pipelines. That is precisely what LinkedIn’s 73% is measuring.

What the Absence Costs

Developers who rely entirely on GitHub are competing on the same axis as every other developer with a GitHub account. That is not a favorable ratio.

AI coding tools are producing code faster and at greater volume than any individual developer can match through side projects. Raw output is becoming less differentiated as a signal. A repository full of commits no longer carries the implication it carried in 2018.

The developers landing senior roles at companies like Linear and Vercel are not distinguished by their framework preferences. They write clearly about decisions: trade-offs they considered, constraints they operated within, systems they changed and then measured.

If you have 3 repositories and 3 documented case studies, you are ahead of the majority of applicants at the senior level. If you have 50 repositories and nothing written, you are invisible to the 73% of decision-makers who weight communication over code. The math is simple. The execution is not, which is why most people keep adding repositories instead.

Pick one project you shipped in the last 18 months. Write 700 words focused on the constraint that mattered most — not the implementation, not the stack, the constraint. Publish it on Hashnode this week.

The truth most developers do not want to sit with: writing a case study about your work forces you to find out what you actually understood about it.

Enjoyed? Clap 👏, Share, Subscribe, and Follow for more!