What your profile README actually does
Your GitHub profile README is the first thing a stranger sees.
One question trips up almost everyone who writes one: should you feature finished projects, or is it okay to show work in progress?
The honest answer is that both can work, but they do different jobs.
This guide walks through what each choice signals, when to use it, and how to describe unfinished work without making it look abandoned.
GitHub lets you create a profile README that appears at the top of your profile page.
You decide what goes in it, so you have full control over how you present yourself.
Common sections include an about-me blurb, contributions you are proud of with context, and guidance for getting help in communities where you are involved.
You can format all of it with GitHub Flavored Markdown, including emoji, images, and GIFs. GitHub's profile documentation describes these options in detail.
That control is the whole point.
Your README is not an automatic feed of everything you have done.
It is a curated front page, which means every item you add is a claim about what you want to be known for.
Alongside the README, you can pin up to six public repositories or gists to your profile.
Pinned items sit near the top and show key details, working with your README as a single first impression.
GitHub's pinning guide covers how to choose and reorder them.
What finished projects signal
A finished project is a complete claim.
It says: I set out to build something, I finished it, and here is the result.
For collaborators, clients, and hiring managers, that completeness matters because it reduces uncertainty.
They can look at the code, run it, and judge the outcome without wondering whether the hard parts were ever done.
Finished work is also easier to describe.
You can state what the project does, what problem it solves, and what you learned, all in the past tense.
There is no hedging.
The tradeoff is that finished projects can make you look static.
If your README only shows work from a while ago, a visitor may wonder what you are doing now.
That is especially true for students and early-career builders whose most recent learning is often their most relevant story.
What work in progress signals
Unfinished work tells a different story.
It says you are actively building, learning in public, and willing to show imperfect things.
For community builders and founders, that openness can be an asset: people often engage more readily with something they can influence than with something already sealed.
The risk is ambiguity.
An unmarked repository with a stale commit history reads as abandoned, not active.
Visitors cannot tell the difference between 'I am building this right now' and 'I gave up on this months ago' unless you tell them.
That is why labeling matters more than the choice itself.
There is also a credibility tradeoff.
If everything on your profile is in progress, a visitor has nothing concrete to evaluate.
A profile full of half-built ideas can read as someone who starts things but does not finish them, even when that is unfair.
A practical way to decide
Instead of a rigid rule, ask what a visitor to your profile is trying to do, and what you want them to come away with.
- If the visitor needs proof of ability , such as a potential client or collaborator checking your skills, lead with finished work. Completeness is the evidence they are looking for.
- If the visitor is deciding whether to work with you now , such as a community member or fellow builder, one clearly labeled project in progress shows momentum and gives them something to join.
- If you are early and have little finished work , describe your in-progress projects honestly and specifically. A well-documented learning project beats a vague claim of expertise.
Most strong profiles end up being a mix: one or two finished pieces as anchors, plus a current project that shows where you are heading.
The finished work establishes that you can complete things; the current work shows you are still moving.
How to describe work in progress well
If you include unfinished projects, the description does the heavy lifting.
A few habits make the difference between 'active' and 'abandoned'.
- Say the status explicitly. A short line such as 'work in progress: currently building the data layer' removes all guesswork.
- State what is done and what is next. Even two bullet points, one for completed parts and one for planned parts, gives a visitor a clear picture.
- Explain why it is unfinished. 'Paused until I finish exams' or 'rewriting the parser after learning a better approach' turns a gap into context.
- Keep the scope honest. A small project you actually finish is a stronger signal than an ambitious one that never lands.
Your contribution graph and activity timeline are public for public repositories and show when you last committed.
GitHub's contributions documentation explains what viewers see.
If you label a project as active, your recent activity should roughly back that up.
If it does not, adjust the label rather than the truth.
Structuring the README around both
A simple structure keeps both types of work readable:
- A one- or two-sentence about-me section describing what you build and why.
- A short list of finished projects, each with what it does and one thing you learned or are proud of.
- A 'currently building' section with one or two active projects, their status, and what help or feedback you would welcome.
- Optionally, guidance for how people can reach you or get involved.
This mirrors GitHub's suggested examples: an about-me section, proud contributions with context, and community guidance.
The profile docs note you choose what to include, so treat this as a starting point, not a required template.
Use your pinned repositories to reinforce the README.
Pin finished work you want judged, and at most one active project you want attention on.
With six pins available, you have room for both without crowding.
Common mistakes to avoid
- Listing everything. A README that catalogs every repository forces the visitor to do the curating. Pick the few that represent you.
- Unlabeled stale repos. If a project is dormant, either say so or leave it off the README and unpinned.
- Vague progress claims. 'Coming soon' with no detail tells a visitor nothing. Name the next concrete step instead.
- Overpromising. Describing an idea as if it were shipped invites disappointment when someone actually looks.
Privacy and visibility considerations
Everything in a public profile README is visible to all GitHub users.
GitHub's documentation is explicit that public profile details can be seen broadly, including in regions where local norms may pose risks to expressing your identity.
It respects your decision whether or not to share information.
It lists exactly which elements stay visible when a profile is set to private, including your README, bio, and profile picture.
Read the visibility notes before adding personal context.
If you are weighing what personal details to include, think through that decision separately.
Our guide on whether to put personal information on your GitHub profile walks through it.
Connecting this to your next opportunity
For founders, freelancers, and students, the README is often the bridge between participation and proof.
A finished project demonstrates you can deliver; a well-described work-in-progress invites people into what you are doing next.
Both convert attention into conversation, which is where opportunities actually start.
If you are building a portfolio from scratch, our guide on building a proof-of-work portfolio with no experience shows how small completed pieces add up.
And if you are deciding what belongs on the profile at all, start with what to put on your GitHub profile, then refine with whether achievements belong there.
The bottom line: finished projects earn trust, work in progress earns engagement, and clear labels let you use both without confusing anyone.
Curate deliberately, describe honestly, and update the labels whenever reality changes.
Take the next step with Ideoreto. Use the ideas in this guide as a starting point for your next project.
Register for Ideoreto to get started.