← Back to Blog

Writing a README That Sells Your Project Without Overselling Yourself

TL;DR

  • Your README is the first and often only thing a reviewer reads before deciding whether to look further.
  • A good README explains what the project does, why it exists, how to run it, and what technical decisions you made.
  • The "why I built this" section needs to be honest and brief. One or two sentences.
  • Screenshots and a live demo link dramatically increase the chance a reviewer spends more than 30 seconds on your project.
  • Weak READMEs are almost never better than no README. Write one worth reading.
  • There is a clear template. Use it.

When someone opens your GitHub repository from a resume or LinkedIn link, the README is what they see first. Before they look at a single line of code, before they check your commit history, before they click through to your deployed app, they read the README.

Or they don't. Because it's just a header and a couple of lines saying "this is my todo app built with React." And then they close the tab.

The README is the cover letter for your project. Unlike an actual cover letter, people actually read it.

What a weak README looks like

Here are the patterns that appear on most junior portfolio READMEs:

The minimal header: ```

MyApp

This is a web app I built. ```

The feature list without context: ```

Features

  • User login
  • Create posts
  • Comment on posts
  • Delete posts ```

The setup instructions that don't work: ```

Installation

Clone the repo and run npm install, then npm start. (Note: you'll need to add your own API keys) ```

The "why I built this" that explains nothing: I built this project to learn React and practice full-stack development.

None of these are technically wrong. All of them miss the point.

A reviewer reading your README is trying to answer three questions in about two minutes:

  1. What does this thing do, and why does it exist?
  2. Can you explain technical decisions like someone who understood what they were doing?
  3. Is this project actually finished and working?

Weak READMEs don't answer those questions.

What every portfolio README needs

Here's the structure. Adapt the order slightly based on your project, but include all of it.

1. Project title and one-sentence description

The title is your repo name. Under it, one sentence that says what the project actually does. Not what technologies it uses. What it does.

Bad: "A full-stack application built with Rails and React."

Good: "A task management app for small teams that tracks who owns what and when it's due."

The second version tells me what the project is. The first one tells me nothing I couldn't see from the file list.

2. Screenshot or demo link (near the top)

Put a screenshot or a link to the live app early. Not at the bottom. Not buried. Right after the description.

If the app is deployed, link it: [Live demo](https://yourapp.com)

If it's not deployed, include a screenshot. A good screenshot shows the app in an actual used state, not a blank empty state. Show data. Show the interface working.

Many reviewers will click the demo link or look at the screenshot and make a judgment before reading another word. Give them something to look at.

If deploying seems complicated, here's a walkthrough of how to deploy a portfolio project to a platform that makes it straightforward.

3. Problem statement

This is the section most READMEs skip. It's the most important one.

What problem does this project solve? For whom? Why does that problem need a software solution?

For real-world projects, this is usually clear. For portfolio projects, candidates often skip it because the honest answer is "there is no problem, I built this to learn Rails." That's fine. But you can still write a better version:

"I wanted to practice building a backend with authentication and file uploads, so I built a recipe sharing app that lets users post recipes with photos and tag them by dietary restrictions."

That's still honest about the purpose (practice), but it describes a coherent use case and shows you thought about what you were building. That's better than "I built this to learn Rails."

4. Tech stack

List what you used. Be specific.

Good: ```

Tech Stack

  • Backend: Ruby on Rails 7.1, PostgreSQL
  • Frontend: Hotwire (Turbo + Stimulus), Tailwind CSS
  • Authentication: Devise with JWT
  • File storage: Active Storage with S3
  • Testing: RSpec, Factory Bot
  • Deployment: Render ```

Not this: ```

Technologies Used

  • Ruby
  • Rails
  • React
  • CSS ```

The difference matters. The specific versions and library choices show you know what you actually used. "CSS" is a language. "Tailwind CSS" is a decision.

5. Setup and installation instructions

Write these so they actually work. This means testing them.

Start from a fresh clone. What does someone need installed? What environment variables need to be set? What commands do they run? In what order?

# Clone the repo
git clone https://github.com/yourname/projectname.git
cd projectname

# Install dependencies
bundle install
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your own values (see below)

# Set up the database
bin/rails db:setup

# Start the development server
bin/dev

Then list what environment variables are needed, what they're for, and where to get them. You don't need to include actual keys, but you do need to explain what service each key connects to.

This section is often broken on portfolio READMEs. Test it. A reviewer who tries to run your project and hits an undocumented dependency or missing setup step will give up and move on.

6. Architecture and technical decisions

This is where you distinguish yourself from every other candidate with a todo app.

Explain one or two choices you made and why. Not every decision. Pick the ones that were interesting or non-obvious.

Examples of what to cover here: - Why you chose a particular library over alternatives - A performance tradeoff you made consciously - How you structured the data model and why - An approach you tried that didn't work and what you did instead - Something you implemented yourself rather than using a library

Example:

Why not use Devise for authentication?

I wanted to understand the authentication flow end to end, so I implemented it from scratch using bcrypt and Rails sessions rather than using Devise. This added complexity to the controller layer but gave me a clearer picture of how session management and password hashing actually work. For a production app I'd use Devise.

That's two short paragraphs. It shows you made a deliberate choice, understood the tradeoffs, and can reflect on when you'd make a different choice. That's the kind of thinking that stands out in a junior candidate.

7. What you'd do differently

Include a short section on what you'd change. Two to four bullet points.

This is counterintuitive. Why highlight weaknesses?

Because it demonstrates technical maturity. Engineers who can't identify the limitations of their own work are harder to work with than engineers who can. Saying "I'd add proper error handling to the API layer rather than just returning 500s" or "I'd extract the notification logic into a background job rather than running it in the request cycle" signals that you understand the gap between learning-project code and production code.

Keep it honest and specific. Don't say "I would make it better." Say what you'd actually do.

8. Future work (optional)

If you're still actively developing the project, list what's coming. This also works as a way to acknowledge features you started but didn't finish:

Planned features - OAuth login with GitHub - Email notifications for comment replies - Export to CSV

This shows the project is alive and that you have a product roadmap, even a simple one.

Writing the "why I built this" section without sounding self-indulgent

The section that candidates handle worst is the one explaining motivation.

Some versions of this are self-indulgent:

"I've always been passionate about productivity software. As someone who struggles with organization myself, I knew I could build something that would help people like me. This project is a reflection of my journey as a developer and my desire to make a positive difference in people's lives."

No reviewer wants to read this. It's about you, not the project.

Other versions are too minimal:

"I built this to practice React."

That's not a description of a project. It's a description of an exercise.

The right version is one or two sentences that answer: what was the specific thing you wanted to learn or build, and why did you make the choices you made to learn it?

"I built this to get practice with real-time features. I used Action Cable rather than a polling approach because I wanted to understand WebSocket connections before using a higher-level abstraction like Pusher."

Clear purpose. Specific technical choice with a reason. Done.

The README as a conversation starter

In an interview, the reviewer will often look at your GitHub the day before your call. If your README clearly explains your technical decisions, they'll ask about those decisions. That's a conversation you want to have, because you know the material and you've already thought about it.

A reviewer who doesn't understand what your project does from the README won't ask about it. They'll move on to the next section or ask generic questions instead. You miss the chance to talk about something you built.

Write the README with the interview in mind. What would you want to be asked about?

What strong READMEs have in common

Looking across projects that consistently get positive feedback from hiring managers:

  • The first paragraph tells you what the app does and who it's for.
  • There's a working demo link or at minimum a screenshot.
  • Setup instructions have been tested and actually work.
  • The technical decisions section exists and says something specific.
  • The writing is clean. Short sentences. No filler.
  • The "what I'd do differently" section is honest and thoughtful.

The common thread is that they treat the README as real documentation rather than a formality.

Before you link the project anywhere

Before you add this project to your resume or GitHub profile:

  • Does the first sentence describe what the app does in plain language?
  • Is the demo link working?
  • Have you run the setup instructions from scratch on a clean environment?
  • Does the tech stack section show specific libraries and versions?
  • Is there at least one paragraph explaining a technical decision?
  • Is the README spell-checked and formatted properly?

If any of these are no, fix them before you apply.

For a full checklist of what to verify across your GitHub portfolio before applying, see the portfolio audit guide. And if your project still needs to be deployed so you can link a live demo, here's how to get a project live quickly.

To understand what reviewers are looking for across your whole GitHub presence, our full GitHub portfolio guide covers what signals matter and which ones don't.

If you want a structured way to build and present portfolio projects that hold up to real scrutiny, here's how the Globally Scoped program works.

Interested in the program?

Apply Now