How to write a README for a portfolio project that a hiring manager will actually read

A portfolio project README has one job that a normal README does not: it has to convince a stranger, in under a minute, that you built something real and understood what you built. Most README guides are written for a different reader. They assume a user who wants to install your library, so they put installation first, a feature list second, and a contributing section at the end. A reviewer screening candidates does not want to install anything. They want to know what the project is, whether it works, what was hard about it, and which part is yours.

So write the top of the README for that reviewer, and put the install-and-run material underneath for the rare person who does clone it. The rest of this guide shows how: what a reviewer sees before they reach your README, a section-by-section structure with a full example, the GitHub rendering rules that quietly break READMEs, and a five-minute check to run before your first application goes out.

Key Takeaways

• A reviewer sees your repository’s one-line description and topics before the README. Fill in the About panel first, because the pinned card on your profile shows the description and nothing from the README.
• Open the README with three things: one sentence on what the project does, a live link or screenshot as proof that it runs, and one sentence on the hardest problem you solved.
• Name the technical decisions and say why you made them. “Used PostgreSQL” tells a reviewer nothing. “Used PostgreSQL row locks instead of Redis so the queue survives a restart” tells them how you think.
• Every command in “How to run” should work from a fresh clone. Test it in a clean directory before you pin the repository.
• For team or course projects, say exactly which parts you built. Reviewers will ask about it in the interview anyway.

What does a reviewer see before your README?

The README is not the first thing anyone reads. A reviewer who opens your GitHub profile first sees up to six pinned items. GitHub lets you select up to six repositories and gists, combined. Each pinned card shows the repository name and its short description, which comes from the About panel, not from the README. Click through, and the repository page shows the About sidebar (description, website link, topics) beside a file list, with the README rendered underneath.

That order matters. A great README behind a blank description and no topics is a README many reviewers never scroll to. Here is everything that renders before or alongside the README, and what GitHub allows in each:

Surface	Where it shows	What GitHub allows
Repository name	Pinned card, page header, search	Rename in Settings; GitHub redirects the old URL
Description	Pinned card, About sidebar, search results	One line of plain text, set via the gear icon next to “About”
Website	About sidebar	One URL. Put your live demo here
Topics	About sidebar, topic search	Lowercase letters, numbers and hyphens, 50 characters or less each, no more than 20
Social preview	Link unfurls in Slack, LinkedIn and similar	PNG, JPG or GIF under 1 MB; at least 640×320, 1280×640 recommended
License	About sidebar	Detected from a LICENSE file

Two of these deserve a note. Topics act as a visible stack summary: a reviewer hiring for a Go backend role can see go, postgresql and grpc before reading a word of prose. And the social preview is what a recruiter sees when you paste a repository link into a message. Until you add one, GitHub’s docs say the link expands to basic repository information and your avatar.

If you are still deciding which repositories deserve pinning at all, settle that first with how to choose which GitHub projects belong on your resume. The broader profile pass (pins, bio, stale forks) is covered in how to make your GitHub profile look professional.

How should a portfolio README be structured?

Put the reviewer’s questions first and the user’s questions second. GitHub’s own docs list what README files typically cover: what the project does, why it is useful, how users can get started, where to get help, and who maintains it. For a portfolio project, keep the first three, add two the docs do not mention (the decisions you made and what you would do next), and drop “where to get help”, since nobody is filing support tickets against a portfolio piece.

This is the order that works:

1. Title and one-sentence summary. What it does and for whom, in plain words. No slogans.
2. Proof it runs. A live demo link, a screenshot, or a short GIF, placed above everything else.
3. Why it exists. Two or three sentences on the problem. If you built it to learn something, say that honestly. It is a perfectly good reason.
4. Stack and key decisions. The technologies, and for the two or three choices that mattered, the reason you made them and the tradeoff you accepted.
5. How to run it. Prerequisites and copy-paste commands, including how to run the tests.
6. Architecture, if it has any. A short diagram or a paragraph on how the pieces connect.
7. Testing and CI. What is tested and how, with a status badge only if the workflow is real and passing.
8. Limitations and next steps. What does not work yet, and what you would build next.
9. Credits and license. Your role if it was a team project, any tutorial or template you started from, and the license.

Sections 1 to 4 are for the reviewer and should fit on roughly one screen. Sections 5 to 9 are reference material. A reviewer who reads only the first screen should still come away knowing what you built and how you think.

A complete example README

Here is the structure applied to a small, made-up project: a URL shortener built for a backend portfolio. The project is invented for illustration; the shape is the point.

# linkcut

A self-hosted URL shortener with per-link click analytics, built to practise
designing a write-heavy API in Go.

**Live demo:** https://linkcut-demo.example.com (resets nightly)

![Dashboard showing click counts per short link over the last 7 days](docs/dashboard.png)

## Why I built it

I wanted a backend project with a real performance constraint. Redirects have
to be fast, while click logging can lag a little, so the interesting problem
is keeping the two paths apart.

## Stack and decisions

- **Go + net/http**, no framework: the API has six routes and I wanted to
  understand the middleware chain rather than configure one.
- **PostgreSQL** for links and an append-only clicks table. I considered Redis
  for counters but chose a single datastore so the demo runs from one
  `docker compose up`. The cost: analytics queries are slower, which I
  mitigate with a nightly rollup table.
- **Click logging is asynchronous**: the redirect handler pushes to a buffered
  channel and a worker batches inserts every 500 ms. A crash can lose up to
  one batch; I accepted that for a demo and document it below.

## Run it locally

Requires Docker 24+.

```bash
git clone https://github.com/your-username/linkcut.git
cd linkcut
cp .env.example .env
docker compose up --build
```

The API listens on http://localhost:8080. Run the tests with `make test`.

## Architecture

```mermaid
graph LR
  Client --> API[Go API]
  API -->|redirect lookup| DB[(PostgreSQL)]
  API -->|click event| Q[Buffered channel]
  Q --> W[Batch worker] --> DB
```

## Testing

Unit tests cover the slug generator and handlers; an integration test runs
against a real Postgres container in CI.

## Known limitations

- Up to 500 ms of clicks can be lost on a crash (see "Stack and decisions").
- No authentication on the admin dashboard; it is meant to run privately.

## Next steps

Rate limiting per API key, and moving the rollup job to a proper scheduler.

## License

MIT

Notice what the example does not contain: a feature list of twenty bullet points, a wall of badges, or adjectives about itself. Every claim in it can be checked by opening the code. That is the whole trick. It also hands an interviewer two easy questions (“why a buffered channel?” and “what would you do about the lost clicks?”), and you already know the answers.

The same decisions you write here can be reused on your resume. How to describe GitHub projects on a resume shows how to turn a README’s “key decisions” section into two strong bullets with real numbers.

How do you write the first screen?

Lead with the outcome, then the proof, then the hard part. The first screen is where most portfolio READMEs fail, usually in one of two ways. Some never say what the project does. Others are still the boilerplate a project generator wrote, with “Getting Started” instructions for a framework rather than for your project.

Compare two openings for the same project.

Before:

# my-app

This project was bootstrapped with a starter template.
Available scripts: npm start, npm test, npm run build.

After:

# Shelf

A reading tracker that imports your Goodreads export and shows reading
pace by month. Built with React and a small Express API.

**Live:** https://shelf-demo.example.com

The hard part was parsing inconsistent export files: the importer handles
three date formats and deduplicates editions of the same book.

The second version answers what, proof, and hard part in four lines. A reviewer who stops there still knows you built a working app and dealt with messy real-world data.

A few rules for the first screen:

• Write the summary for someone outside your field. “A reading tracker” beats “a full-stack CRUD application leveraging modern technologies”.
• Put the proof above the fold. A working link outranks any amount of description. If the project cannot be hosted, a screenshot or a 10-second GIF of the main flow is the next best thing. Keep it small, since a huge GIF makes the page slow to load.
• Name one hard problem. It turns “I made an app” into “I solved something”, and it gives the reviewer a question to ask you.

Which GitHub rendering rules break READMEs?

A handful of GitHub behaviours trip people up, and they are all in the docs.

Which file GitHub shows. GitHub surfaces a README placed in the hidden .github directory, the repository root, or the docs directory. If there is more than one, it picks in that order: .github first, then root, then docs. A stale .github/README.md left over from a template will hide the root README you actually maintain.

Length. Anything beyond 500 KiB is truncated when viewed on GitHub. You are unlikely to hit that with prose, but pasted logs or inline data can get there. GitHub’s docs also suggest moving longer documentation to a wiki, and that advice applies to portfolio projects too.

Navigation is automatic. GitHub generates a table of contents from your headings under the “Outline” menu, and every heading gets a linkable anchor. You do not need a hand-written table of contents. Clear headings do that job.

Use relative links for files in the repo. Write [design notes](docs/DESIGN.md) rather than a full github.com/.../blob/main/... URL. GitHub rewrites relative links for whichever branch the reader is on, and its docs note that absolute links may not work in clones. Keep link text on one line; a link split across lines does not render.

Diagrams render from text. GitHub renders Mermaid, GeoJSON, TopoJSON and ASCII STL inside fenced code blocks, so an architecture diagram like the one in the example above lives in the README as text and stays editable.

Alerts are for warnings, not decoration. GitHub supports five alert types: [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] and [!CAUTION]. GitHub’s own guidance is to limit them to one or two per article and avoid placing them back to back. A portfolio README rarely needs more than one, for something like “the demo database resets nightly”.

Status badges should be real. A GitHub Actions badge uses the format https://github.com/OWNER/REPOSITORY/actions/workflows/WORKFLOW-FILE/badge.svg (GitHub Docs). One passing CI badge is a small, checkable signal. A wall of decorative badges from a badge generator is noise, and a red “build failing” badge on a pinned repository is worse than no badge at all. If you have not set up CI yet, what is GitHub Actions explains the basics.

What should you leave out?

Leave out anything a reviewer cannot verify or would not miss.

• Untouched template text. If a framework generator wrote the README, either rewrite it or delete it. Leaving it signals that nobody looked at this file after the first commit.
• Inflated claims. “Scalable”, “production-ready” and “enterprise-grade” invite the question “under what load?” Unless you have numbers, describe what the code does.
• Feature lists longer than the code. Five honest features beat twenty aspirational ones, especially when half are unchecked boxes.
• Secrets and personal data. Check screenshots for API keys, real email addresses and other people’s data before you commit them. The commit history keeps them even after you delete the file.
• A missing license, if you want people to reuse it. Without a license, GitHub’s docs explain that default copyright laws apply and nobody may reproduce or build on the code. For a portfolio piece that is not fatal, but a one-line MIT or Apache-2.0 license removes the question.

How do you handle team, course and tutorial projects?

State your part plainly, near the top. Group projects and bootcamp capstones are normal portfolio material, but a README that says “we built” with no detail leaves the reviewer guessing which parts are yours, and the interviewer will ask.

A credits line like this solves it:

Team project (4 people) for CS 3200. I built the search API and the Postgres schema; teammates built the React frontend and auth. My commits are in api/ and db/.

The same goes for tutorial projects. Say which course or tutorial you followed and what you changed or added afterwards. A rebuilt tutorial with one genuinely new feature, honestly labelled, is fine. A tutorial presented as original work falls apart in the first technical conversation. If most of your public work is coursework, how to write a developer resume with no professional experience covers how to present it.

How do you check a README in five minutes?

Read it the way a reviewer would, then run it the way a stranger would.

1. Ten-second test. Open the repository in a private browser window. Without scrolling, can you tell what it does and whether it works? If not, fix the first screen.
2. About panel test. Is there a description, a website link if a demo exists, and three to six accurate topics?
3. Clean-clone test. Clone into a fresh directory and follow “How to run” word for word. Any step you had to improvise is a missing line.
4. Claim test. For every sentence that claims something (“handles 10,000 rows”, “fully tested”), can you point to the code or test that proves it? If not, cut it or soften it.
5. Resume match. Does the resume bullet for this project describe the same thing the README describes? Reviewers notice when the two disagree.

resumefromgit.com can do part of this across a whole profile. Enter a GitHub username and the repository health section reports, for your top repositories, whether a README.md exists on the default branch and whether GitHub Actions workflows are present. Its discoverability score counts four About-panel signals per repository: a description, topics, a license and a website link. The improvement list flags pinned repositories with no description or no topic tags. Be aware of what this measures. The README check looks for a file named exactly README.md at the repository root, so it reports presence, not quality, and a README kept only in docs/ will not be counted. The quality part is still yours.

To see how strong maintainers present many repositories at once, browse the developer showcase. The solo maintainers behind open-source projects list is a good place to study short, consistent READMEs at scale.

Frequently asked questions

How long should a portfolio project README be?

Long enough to cover the nine sections above and short enough that the first four fit on about one screen. For most portfolio projects that comes to somewhere between half a page and two pages of rendered text. If it is growing past that, move design notes into a docs/ folder and link to them with relative links.

Is a project README the same as a GitHub profile README?

No. A project README lives in each repository and explains that project. A profile README lives in a special public repository named after your username and appears at the top of your profile page. They do different jobs, and you want both. The profile README is covered in how to write a GitHub profile README.

Should I use a README generator or an AI tool to write it?

Use one for scaffolding if it helps, then rewrite every sentence that makes a claim. Generated READMEs tend toward the same generic feature lists and adjectives, and they cannot know which decisions were hard or why you made them, which is the part reviewers care about. Whatever you publish, you should be able to defend every line in an interview.

Do recruiters actually read READMEs?

Some do, and technical interviewers are more likely to than sourcers. The honest picture of who checks GitHub, and when, is in do recruiters actually check your GitHub. The practical upshot is that the first screen has to work for someone skimming, and the rest has to hold up for an engineer preparing interview questions.

Should every repository on my profile have a README?

Every pinned repository should. For the rest, a one-line description and a two-sentence README is enough. Old experiments can be archived instead of documented.

Write the README you would want to receive

A good portfolio README is not marketing. It is a short, checkable account of what you built, why you built it that way, and what you would change. Write the first screen for the reviewer, test the run instructions from a clean clone, cut every claim you cannot back up, and fill in the About panel so the pinned card says something true.

Then look at the whole profile the way a reviewer will. resumefromgit.com turns any public GitHub username into a visual CV and a free, ATS-friendly PDF resume, built only from the account’s own data, so you can see which repositories surface and how they read before anyone else does.