Turn a GitHub Repository Into a Portfolio Asset That Converts

I once spent a month building a tool that turns network sequence descriptions into clean diagrams. It worked. It was genuinely useful. And for a while its entire public presence was a README that said, more or less, "SequenceFast, a sequence diagram tool" followed by an npm install line.

Anyone who landed on that repo had no idea what they were looking at. Not what problem it solved, not what it looked like, not whether it was abandoned or alive. The code was the best thing I'd built that semester and the repo made it look like a forgotten weekend experiment. That gap, between what the work was and what the repo communicated, is the entire subject of this post.

A GitHub repository is not a portfolio asset by default. It's a folder. Turning it into proof of work is a deliberate act, and most developers, myself included, skip it because the code feels like it should speak for itself. It doesn't. Nobody reads your source before they've decided whether you're worth taking seriously. They read the top of the README, look at a screenshot if there is one, and decide in about fifteen seconds.

The README is the landing page, so treat it like one

The single highest-leverage change I made across my repos, rnvs-sequence-diagram-tool, aical, priotask, myuninotes, openAIScientist, was rewriting the top of every README to answer three questions in the first screen, before any installation instructions:

• What is this, in one plain sentence?
• Who is it for and what problem does it kill?
• What does it look like or do? (A screenshot, GIF, or live link.)

Here's the shape of the before and after. The before was something like:

SequenceFast
============

A sequence diagram tool.

Install:
  npm install ...

The after leads with the value and the proof:

SequenceFast
============

Turn plain-text network sequence descriptions into clean,
shareable diagrams, no drag-and-drop, no GUI fiddling.

[ demo.gif ]

Built for students and engineers documenting protocols who
want diagrams from text they can version-control.

The difference isn't more words. It's ordering by what a stranger needs first. Installation instructions are for people who've already decided. The top of the README is for people deciding. Put the demo above the fold and you've answered the only question that matters, "does this do something real?", before the reader has to do any work.

Toggle between the two and watch the first screen change job entirely:

# SequenceFast

A sequence diagram tool.

## Install
npm install sequencefast

## Usage
sequencefast input.txt

# (a stranger learns nothing about
#  what problem this kills, or whether
#  it's alive. they leave.)

The top of the README has to answer three questions before any install instructions. Switch between them:

Show it running, not just describe it

A claim is weak; a recording is strong. The cheapest credibility upgrade for any repo is a short GIF or screenshot of the thing actually working. For aical, a calendar tool, one GIF of an event being created does more than three paragraphs of feature bullets. For a CLI, an asciinema-style recording of real commands and real output is worth more than a usage table.

I'm deliberate about this because of how people evaluate developers now. A recruiter or a fellow engineer is pattern-matching for signal under time pressure. "Here's a clip of it working" is unfakeable signal. "Here's a list of technologies I used" is not, anyone can list React and Postgres. The recording proves the thing exists and runs, which is the actual question behind every portfolio review: did this person ship something, or just start something?

If a project is deployed, the live link beats everything. A working demo URL at the top of the README is the strongest single line you can write. For my deployed projects I link straight from the repo, and I link the same projects from /#projects on my site so the two reinforce each other, the portfolio sends people to the proof, the proof points back to the portfolio.

Tell the story the commit history can't

Code shows what you built. It doesn't show why, and "why" is where the credibility lives. The README section I now refuse to skip is a short honest account of the decisions:

I built openAIScientist because I kept wanting to run the same multi-step LLM experiments by hand. The interesting problem wasn't calling the API, it was making runs reproducible and comparable. So the design centers on...

Two or three sentences like that do something no test suite can: they show judgment. They show you understood the problem, considered tradeoffs, and chose. A reviewer reading that learns more about whether they'd want to work with you than they would from skimming a thousand lines of TypeScript. This is the part that converts a "neat project" into "I want to talk to this person," and it costs you ten minutes of honest writing.

The honesty matters. If something is half-finished, say so. "Auth is stubbed, this was a learning project for the diffing logic" reads as confidence, not weakness. Pretending a prototype is production reads as the opposite the moment someone clicks into the code. I'd rather a strong scoped claim than an oversold one that collapses on inspection.

There is a tradeoff buried in this section that took me a while to get right: how long the "why" should be. My first attempt at openAIScientist had a "Motivation" section that ran nine paragraphs, with a literature-review tone and a wall of context about LLM evaluation. Nobody read it. I watched the analytics, the README, and the time-on-page sat under twenty seconds, which means readers were bouncing off the wall of text before they reached the demo. So I cut it to three sentences and moved the demo above it. Time-on-page roughly tripled. The lesson is that the "why" earns its place only when it is short enough to read in the same fifteen-second window everything else competes for. Lead with the one decision that shows judgment, the reproducibility problem in my case, and stop. If a reader wants the nine paragraphs, that is what a linked write-up or a blog post about the project is for, not the README. The README's job is to make someone want the long version, not to be it. I treat the story section like a movie trailer: enough to prove there is a real film behind it, never the whole plot. The same instinct that keeps the demo under fifteen seconds keeps the story under three sentences.

There is an uncomfortable mechanic underneath all of this. Guess how it works:

Make the repo legible to a tired reviewer

Beyond the README, there's a layer of repo hygiene that people read as competence signals whether or not they consciously notice them. I think of it as making the repo legible to someone who is skimming a dozen projects in an afternoon and has no patience.

The cheap, high-signal ones:

• A description and topics filled in, so the repo isn't anonymous in search and on your profile grid.
• A license file, because its absence quietly tells anyone evaluating you that they legally can't use the code, and that you didn't think about it.
• A clean recent commit or two, so the repo doesn't read as abandoned. A project that was last touched two years ago with a commit message of "wip" looks dead even if it isn't.
• Issues or a short roadmap, even a tiny one, which signals the project is something you reason about rather than dumped.

None of this is about gaming a metric. It's that an evaluator under time pressure substitutes presentation quality for code quality, because reading the code is expensive and reading the surface is free. priotask and aical get more charitable reads than my throwaway repos not because the code is dramatically better, but because the surface tells the reviewer "this person finishes things and cares how they're presented." That inference is what you're actually buying with the polish.

Between shifts at BMW and coursework for my M.Sc. CS at LMU, I rebuilt the top of my own READMEs around a few load-bearing lines, and the annotated version below is the exact skeleton I now reach for. Each note marks a line that does disproportionate work in the first few seconds a stranger spends on the repo.

# Project, one line of what it does

![demo](demo.gif)

## Why it exists
## Quickstart (copy-paste runnable)
## How it works (the interesting part)

The skeleton is deliberately short because the README earns its keep in the first screen, not the tenth. Once those lines are in place, the rest of the document can sprawl as much as it needs to.

I'll be blunt about the failure mode I see constantly, including in my own past profiles: developers pour weeks into the code and zero minutes into the surface, then conclude their work "doesn't get noticed." The work didn't fail. The presentation never started. Twenty minutes of repo hygiene per serious project is the highest hourly-return work in your entire portfolio, and it's the work nobody wants to do because it isn't programming.

Curate ruthlessly, not every repo is an asset

This is the unglamorous part. A profile of thirty repos where four are real and twenty-six are tutorials-you-followed actively hurts you. The signal-to-noise ratio is itself a signal. When someone lands on github.com/noluyorAbi, I want the repos that surface to be the ones I'd defend in an interview.

My rules for what gets promoted as portfolio work:

• It solves a real problem I actually had (priotask, myuninotes, aical all started as personal itches).
• The README answers the three questions above.
• There's a demo, screenshot, or live link.
• I'd be comfortable walking someone through the code.

Everything else can stay public, learning in the open is fine, but it doesn't get pinned, doesn't get linked from my site, and doesn't get a polished README. Pinning is editorial. The six pinned repos are a curated statement, not an archive dump. Treat the pins like the front page of a newspaper: limited space, every slot earned.

The math of polishing is worth seeing plainly, because the payoff scales with how few repos you actually finish well rather than how many you start:

That slider holds the whole argument in one place, and the lesson held steady across every profile I cleaned up over the last two years.

Quality over quantity, three polished repos beat thirty abandoned ones

When I trimmed my own profile down, the repos that carried weight were never the ones I had the most of. A wall of thirty repositories where most are tutorials I followed or experiments I dropped reads as noise, and noise buries the four projects I would actually defend in a conversation. Three repos I have genuinely finished do more work than thirty that trail off after the first commit, because a reviewer infers care from what they see polished, not from a count on a profile grid.

So I am concrete about what "polish" means, since the word is easy to wave at and hard to act on. It is a README whose first screen says what the project is, who it is for, and what it does, before any install steps. It is a GIF, a screenshot, or a live demo link that proves the thing runs. And it is the repo being pinned, so the six slots on my profile point a stranger straight at the work I stand behind. Readme, demo, pinned. That is the bar, and it is the part that turns code into a signal someone hires on.

Before you sink an afternoon into any single repo, it helps to know whether that repo is even worth promoting or whether the energy belongs somewhere else entirely. Walk the question below and it will route you to the next concrete move:

Wire the repo into the rest of your presence

A repo in isolation is a dead end for the reader. The conversion happens when the repo connects outward. At the bottom of my serious READMEs I link back to the site and the context behind it, and from the site I link into the repos. That loop matters because different people enter from different doors. A recruiter starts on /cv and clicks through to a repo to verify the claim. A developer finds the repo through a search or a shared link and clicks to /blog to see how I think. Either path should lead somewhere, never to a cul-de-sac.

Concretely, the connective tissue I keep consistent:

• README links to the live demo and to the project's place on my site.
• The site's project section links to the repo and, where it exists, a write-up.
• A blog post explaining a project links to the repo, and the repo links back to the post.

This isn't link-farming. It's making sure that wherever someone enters, they can get to the proof and the story without guessing. The repo, the demo, the project page, and the post are four views of one thing, and the value is in how they corroborate each other.

Open your best repo right now and run it through this the way a stranger would. Each unticked box is a place good work is reading as forgettable:

Recording a demo that proves it runs

Deciding to show a demo is the easy part. Making one that actually lands takes a few deliberate choices, and most of them are about restraint. The first rule I follow: keep it under about fifteen seconds. A reviewer is scanning, not settling in, and a clip that runs a full minute gets closed before the good part. If you can't show the value in fifteen seconds, the problem is usually that you're showing too much.

That leads to the second rule: record the core action and its result, not a tour of the UI. Nobody is impressed by you opening a sidebar, hovering over a menu, and scrolling a settings page. For aical I show one thing, a calendar event going from typed text to a created event, because that single transformation is the entire reason the tool exists. For SequenceFast I'd show input going in and the result coming out, not the navbar. Pick the one moment where your project does its job, and let that be the whole clip.

Third, start from a state a stranger understands. Don't open mid-flow with three tabs already configured and data already loaded; nobody knows what they're looking at. Begin from an empty or obvious starting point so the viewer can follow the cause and the effect without context you forgot to give them.

Fourth, trim the dead time. Cut the loading spinners, the typing pauses, the half-second where nothing happens. Every frame that isn't moving the story forward is a frame someone uses to leave. Editing a fifteen-second clip down to ten makes it noticeably better.

Here is the actual sequence I run when I record a demo for one of my repos, from the empty editor to the file committed alongside the README. It takes me about half an hour end to end, and every step exists to cut a frame a reviewer would otherwise use to leave:

The reason all this effort is worth it comes back to one point: an unfakeable clip of the thing working beats any list of technologies. Anyone can write "React, Postgres, Docker." A recording of the feature doing what you claim is proof you can't bluff. That's the signal a reviewer is actually hunting for, so make it clean.

What a reviewer actually checks in 30 seconds

I want to be honest about how shallow the first pass really is, because once you know what gets checked you know what to fix first. When I open someone's repo, or when I imagine a reviewer opening mine, the same handful of things get read in under half a minute, in roughly this order.

The first line of the README. Not the badges, not the heading, the first sentence of actual content. If it tells me what the thing is and who it is for, I keep going. If it is a clever name with no explanation, I have already half-decided this person doesn't think about the reader. Fix this first, because everything downstream depends on it.

Whether it looks like it runs. I am scanning for a screenshot, a GIF, or a quickstart that is plausibly copy-paste. I am not cloning your repo on the spot. I am looking for evidence that it ran for you and would run for me. A three-command quickstart reads as real; a setup section that makes me guess reads as a prototype that never left your laptop.

Recent commit activity. One glance at the commit list tells me if this is alive or abandoned. A repo last touched two years ago with a message of "wip" looks dead even when the code is fine. A clean commit or two in the last while signals you still stand behind it.

Whether tests exist at all. I am not auditing coverage in 30 seconds. I am checking for the presence of a test directory, because a project with even a thin test suite signals someone who thinks past "it worked once on my machine."

Code readability over cleverness. If I do click into a file, I am reading for clarity, not for how clever you are. Plain code that I can follow beats a dense one-liner I have to decode every time. The same instinct shows up when you study other people's work: see niche GitHub repos worth studying for how the legible ones earn trust fast.

Between BMW shifts and M.Sc. CS coursework at LMU Munich, I fix these in that exact order, because the README first line is cheap and decides whether the rest is ever read.

The honest summary

A repository becomes a portfolio asset the moment a stranger can understand, in fifteen seconds, what you made and why it's good, and then verify it. Everything in this post serves that one outcome: a README that leads with value, a recording that proves it runs, a few sentences of judgment that show how you think, ruthless curation so the signal isn't buried, and links that connect the work to the rest of your presence.

I learned this the slow way, by watching genuinely good work read as forgettable because I never bothered to present it. The code was never the problem. The presentation was. Fixing the presentation cost a few hours per project and changed how the same work landed completely. Your best repo right now is probably underselling you. Go look at the top of its README the way a stranger would, and fix the first screen.

A polished repo is only a promise until someone sees the work behind it, so before you go, let me show you the curated profile I built from this exact playbook.