The portfolio README template: problem and demo first, install steps last
In one audit of 3,000 GitHub repos, only 8% showed even one image. That's your chance to stand out.
A University of Wisconsin–Madison audit of 3,033 GitHub repositories found that only 8% had a README with an image, and only 72% had a README at all. Most project pages open with install steps, so nobody sees what the project does. This template flips the order: the problem in one sentence, a demo GIF, how it works, one real result, what you'd do next, and install steps last.
By Preston KirschnerFounder, AI Career HubUpdated
- What one audit of 3,033 repos found in their READMEs
- The README template (copy it)
- A filled-in example: "delay radar"
- How to make a demo GIF in 10 minutes
- Pin-your-best-3 checklist
- Repos in the audit whose README included even one image.
- 8%
- One audit of 3,033 repos linked to Wisconsin. Not a random sample of GitHub.
- UW–Madison Data Science Institute, Oct 31, 2024
- Repos in the same audit that had a README file at all.
- 72%
- UW–Madison Data Science Institute, Oct 31, 2024
- Repos that had all the basics: README, license, description, homepage and images.
- 0.5%
- "Basics" is the author's own list.
- UW–Madison Data Science Institute, Oct 31, 2024
In this guide
Most READMEs never show the project working
Abe Megahed at the University of Wisconsin–Madison's Data Science Institute pulled 3,033 GitHub repositories that mention Wisconsin in their description, and checked their metadata through GitHub's API. Only 72% had a README file. Only 8% had a README with even one image. And only 0.5% had all of the basics: a README, a license, a description, a homepage and images (UW–Madison, Oct 2024).
That's an audit of mostly university and research code, not a study of job seekers' portfolios. But it points at the same gap: most project pages never show what the project does. A reviewer who opens your repo sees a wall of install commands, or nothing.
We couldn't find a solid recent study of how long recruiters spend on a GitHub profile. (The numbers that circulate online, like "11 seconds", don't trace back to a real survey.) The older evidence that portfolios matter is from HackerRank's 2018 Developer Skills Report, where hiring managers ranked a portfolio of work, such as GitHub, as the #2 qualification after previous experience. That's a vendor survey from 2017 fieldwork, so treat it as background.
The template below is our recommendation: put the problem and a demo where a reviewer looks first, and move install steps to the end.
The README template: copy it into your repo
Create or replace README.md in your repo's root folder with this, then fill in each section. The order is the point: what it is and proof it works come first, setup comes last.
What each section is for
- What to write
- The project name, plus a one-line description if the name isn't self-explanatory
- Rule of thumb
- Say what it does, for whom
- What to write
- Who has this problem and what it costs them
- Rule of thumb
- No tech words yet
- What to write
- A GIF, screenshot or live link
- Rule of thumb
- Show it working in about 10 seconds, above any setup steps
- What to write
- Stack, what it does, what comes out
- Rule of thumb
- 3 bullets. Add a simple diagram if it helps.
- What to write
- One real number or piece of evidence
- Rule of thumb
- Be honest about scale: "in tests" or "for 12 users" is fine
- What to write
- Known limits and what you'd build with more time
- Rule of thumb
- This shows judgment, not just output
- What to write
- Copy-paste setup commands
- Rule of thumb
- Last. Keep it short.
| Section | What to write | Rule of thumb |
|---|---|---|
| Title | The project name, plus a one-line description if the name isn't self-explanatory | Say what it does, for whom |
| The problem | Who has this problem and what it costs them | No tech words yet |
| Demo | A GIF, screenshot or live link | Show it working in about 10 seconds, above any setup steps |
| How it works | Stack, what it does, what comes out | 3 bullets. Add a simple diagram if it helps. |
| Results | One real number or piece of evidence | Be honest about scale: "in tests" or "for 12 users" is fine |
| What I'd do next | Known limits and what you'd build with more time | This shows judgment, not just output |
| Run it locally | Copy-paste setup commands | Last. Keep it short. |
# [project name] ## The problem One sentence: who has the problem, and what it costs them. ## Demo [GIF or screenshot: 10 seconds of it working] ## How it works - [stack] - [what it does] - [the output] ## Results One real number: "[caught/saved/cut] X% of [thing] in [tests/users]" ## What I'd do next - [next improvement] - [edge case you'd handle] ## Run it locally [install steps go LAST]
Filled in: "delay radar"
A fictional project, so you can see the shape. The 80% is an example number. Use your own, and only numbers you can back up.
# delay radar Flags late shipments a day before ops teams would normally find them. ## The problem Ops teams find late shipments a day too late, after the customer has already called. ## Demo  ## How it works - Python + Postgres - Predicts delays from carrier data - Sends a Slack alert at 6am with the shipments at risk ## Results Caught 80% of late shipments a day earlier in tests on 3 months of past carrier data. ## What I'd do next - Add weather data - Handle holiday spikes, when carriers' normal patterns break ## Run it locally git clone https://github.com/[you]/delay-radar cd delay-radar pip install -r requirements.txt cp .env.example .env # add your database URL and Slack webhook python main.py
Illustrative example, not a real project. Notice the results line says where the number came from ("in tests on 3 months of past data").
Make a demo GIF in about 10 minutes
The demo is the section most READMEs skip, and the one that shows the project is real. It doesn't need editing or narration. Here's our quick method.
- Plan one path. Pick the single thing that shows the project working: input goes in, result comes out. Aim for about 10 seconds.
- Clean the screen. Close other tabs, hide bookmarks and notifications, and use sample data, never real customer or personal data.
- Record it. On a Mac, press Cmd+Shift+5. On Windows, use the Snipping Tool's record option or ScreenToGif. On Linux, use Peek or your desktop's screen recorder. Record just the window, not your whole screen.
- Convert to GIF if your recorder saved a video. One way is ffmpeg (command below). Smaller width and frame rate keep the file light so it loads fast.
- Add it to the repo in a docs/ folder, and reference it in the Demo section with a short description as the alt text.
- No time for a GIF? Use one clear screenshot of the result. It's far better than nothing.
ffmpeg -i demo.mp4 -vf "fps=12,scale=800:-1:flags=lanczos" -loop 0 docs/demo.gif
Lower fps or scale if the GIF is still large. A sharp screenshot beats a blurry, slow GIF.
## Demo  Live version: [link, if you have one]
Pin your three best repos, and give each one this README
A reviewer won't open twenty repos. Pinned repos sit at the top of your GitHub profile, so decide what they see first. Three strong projects beat a long list of half-finished ones. This checklist is our suggestion.
- Pick the three repos closest to the jobs you're applying for. Recent and finished beats big and abandoned.
- Give each one this README, with a demo and one real result.
- Fill in the repo's short description (the "About" box on the right of the repo page). It shows on the pinned card.
- On your profile, choose "Customize your pins" and select the three.
- Archive or make private any forks and tutorial repos you don't want reviewed first.
- Link the profile from your résumé, next to the project bullets that describe the same work.
Your portfolio README
Match your pinned repos to real job posts
Create a free account to save the AI, ML and data roles you're aiming for, so you can check your three pinned projects against what those posts ask for.
See what the jobs ask for
Fresh AI, ML and data jobs, all posted in the last 30 days. Read three posts for the role you want, and pin the repos that match them.
Browse AI jobsSources
- 1.Audit of README, license and metadata completeness in 3,033 GitHub repositories (OSPO post)University of Wisconsin–Madison Data Science Institute (Abe Megahed) · Oct 31, 2024 · 3,033 repos found by searching "Wisconsin" in repo descriptions, via the GitHub API. Not a random sample, not a recruiter study.
- 2.2018 Developer Skills ReportHackerRank · 2018 · Survey fielded Oct 16–Nov 1, 2017: 39,441 developers, 7,000+ employers. Vendor survey.
Facts last checked Oct 22, 2026. Vendor surveys are labelled as such, and our own recommendations are marked as ours. Spot something out of date? Tell us.