The one idea
Most people think GitHub is a place programmers store code. It is more useful than that, and the useful part applies to everyone:
GitHub is a public record of what you did, when you did it, and why.
Three things, and the third is the one people miss. Every change you save carries a message explaining it. Over time that becomes a visible history of your thinking — which is exactly what the portfolio lesson said employers actually want and rarely get.
You do not need to be a programmer to use it. Writers, analysts, researchers, documentation people and students all use it for the same reason: it holds files, it remembers every version, it lets other people comment on specific lines, and it gives you a public link.
A place to keep files where every version is saved, other people can suggest changes, and anyone can see your work at a link.
A repository per project, a README explaining it, commits recording each change with a reason, issues tracking what is left, and pull requests for review before changes are merged.
A hosting layer over Git, a distributed version control system. Git tracks content as an immutable graph of commits; GitHub adds collaboration workflows, access control and static hosting on top.
The vocabulary, once
Six words cover almost everything you will meet.
| Term | What it is | Why you care |
|---|---|---|
| Repository (repo) | A folder for one project, with its full history | One repo per portfolio piece |
| Commit | One saved change, with a message saying why | The message is the record of your thinking |
| README | A file GitHub displays on the repo's front page | The single most important file you will write |
| Issue | A written item of work or a problem, discussable | Shows you plan and track, not just produce |
| Pull request (PR) | A proposed set of changes, reviewable before merging | How teams work; how you contribute to others' projects |
| GitHub Pages | Free hosting for a website from a repo | Turns a repo into a link a recruiter can click |
A commit message is worth dwelling on. "update" tells nobody anything. "Switch to rolling 4-week view — managers said monthly was too slow" is a decision, timestamped and permanent. Two years later that message is the only reason you remember why.
Why the README matters more than the code
For a portfolio, this is the whole lesson.
A reviewer arrives with no context and about ninety seconds. The README is what loads. If it does not tell them what this is, they leave — and no amount of good code below rescues that, because they will never scroll to it.
GitHub's own documentation is direct about the README's purpose: it tells other people why your project is useful, what they can do with it, and how they can use it. Write it for a stranger with no background in your subject.
A README that does its job contains:
- One sentence saying what this is. Not "This project is a web app built with React." Try "A tool that tracks class attendance without a WhatsApp group falling apart."
- The problem it solves, and whose problem. Two or three sentences.
- How to see it working. A live link if there is one. Otherwise a screenshot, or the exact commands to run it — tested, on a clean machine.
- One or two decisions you made and why. The same reasoning the portfolio lesson asked for. This is the section that makes a reviewer remember you.
- What it does not do. Known limitations. Honesty here reads as competence.
- Tools used. One line, at the bottom, where it belongs.
Recommendation If you have limited time, spend it on the README, not on refactoring the code.
The README is read by everyone who visits. The code is read by almost nobody at
the shortlisting stage.
If you do not write code
The mechanics are identical. Files go in, history is kept, a link comes out.
Documentation and writing. Guides, process notes, handbooks, written in
Markdown — a plain-text formatting syntax where # makes a heading and **
makes bold — which GitHub renders automatically. Every edit is tracked, so you
can show how a document evolved.
Datasets and analysis. A cleaned public dataset with a README explaining where it came from, what you fixed and what remains wrong is useful to other people and strong analyst evidence.
Research notes. Reading lists, literature summaries, methodology notes. The commit history shows sustained work over months, which is hard to fake.
Anything collaborative. Two people editing a document via pull requests get a reviewable record of who changed what and why, which a shared document with tracked changes preserves far less well.
A personal site. GitHub Pages hosts a static site from a repository at no cost — the simplest route to a portfolio at a public URL.
An HR generalist keeps a public repo of interview scorecards and onboarding checklists — anonymised, no company names, no candidate data. The README explains the reasoning behind each criterion and what she changed after using them.
No code anywhere in it. It is the strongest artefact in her application, because it shows process design with the reasoning attached.
A statistics student cleans a public government dataset on district-level rainfall. The repo contains the raw file, the cleaned file, the script, and a README that explains the four categories of error found, the decision to drop one district entirely with the reason, and the two known remaining problems.
Small project. Complete evidence. Three of the five portfolio questions are answered in the README alone.
Your first useful repository
1 of 8Create the account with a professional username. This will appear on your resume.
anjali-raooranjalirao-datais fine. Nicknames from school are not.
Try this
Here is a README from a real-shaped student repository:
Project
This is my final year project.
Installation
npm install
Technologies
React, Node.js, MongoDB, Express
Identify what a reviewer cannot learn from this, then write the first two lines of a better version.
Your challenge
Level 3 · IndependentPublish one repository containing something you actually made — code or not.
Success criteria:
- The README answers what it is, whose problem it solves, and how to see it working.
- It contains at least one "I decided X because Y" and one stated limitation.
- No secrets, no personal data, nothing belonging to an employer.
- The repo is pinned on your profile and has a description and topics.
- Someone outside your field reads the README and can tell you what it does.
If you want structured practice with the mechanics first, GitHub's own free courses at skills.github.com run inside real repositories rather than on slides.
What people usually get wrong
- An empty or default README. The most common failure and the most costly.
- Commit messages like "update", "fix", "final". You are throwing away the most valuable thing GitHub gives you for free.
- Uploading a whole course folder as one repo. Forty assignments in one place tells a reviewer nothing. One project, one repo.
- Putting a GitHub link on your resume when the profile is empty. An empty profile is worse than no link, because now they have checked.
- Committing
node_modulesor large data files. Use.gitignore. Nobody wants to clone 400MB of dependencies. - Leaving a private repository private and then linking to it. Reviewers see a 404 and assume you are careless.
- Not pinning anything. Your profile then leads with whatever you touched last, which is usually your worst work.
- Assuming deleting a file removes it from history. It does not, and this is where the security risk lives.
How someone experienced does it
Experienced people use issues on their own projects, even alone. Each issue is one thing to do, written down. A reviewer can then see that you plan work, break it into pieces and close it — which is most of what "can this person work in a team" means in practice.
They write commit messages for a reader six months out: a short line saying what changed, and where the reason is not obvious, a second line saying why. The history becomes a narrative rather than a list of saves.
The strongest single move available to a fresher is one merged pull request on someone else's project — even a small one, fixing a documentation error or a broken link. It shows you can read unfamiliar work, follow someone else's contribution rules, take review comments and see a change through. That is a functioning junior colleague, evidenced publicly and permanently. Look for repositories labelling beginner-friendly issues, and read the project's CONTRIBUTING file before opening anything.
When not to use this
GitHub is not the right home for work that is primarily visual. Designers are better served by a portfolio platform where the images are the point; a repo full of PNG files is awkward to browse.
It is also not a general file backup. It is poor with large binary files, and version history on a 200MB video is not useful to anyone.
And it will not be checked at all in many hiring processes — most non-technical roles, most campus placement drives, most process-driven bulk hiring. Build the repo because it holds your evidence at a link, not because you expect every recruiter to open it.
What Git is actually doing underneath
Git stores your project as a chain of snapshots. Each commit records the full state of the tracked files at that moment, along with a pointer to the commit before it, an author, a timestamp and a message.
Two consequences explain most of Git's behaviour.
History is append-only by default. Removing something means writing new history, not editing the old — which is exactly why a deleted password stays readable, and why cleaning it out is genuinely awkward.
Every copy is complete. When someone clones your repository they receive the entire history, not a working copy pointing at a server. This is what "distributed" means, and it is why a leaked secret cannot be recalled: copies already exist elsewhere, and you have no way to reach them.
Branches, which look complicated, are just movable labels pointing at a commit. Merging is combining two chains. Once the snapshot model is clear, the rest of Git's vocabulary stops being mysterious.
Prove it
Publish one repository with a README a stranger can follow, then put the link in your resume and your LinkedIn Featured section.
The test: send the link to someone in a completely different field and ask them what the project does. If they can tell you, the README works. If they ask "what is this?", it does not — and that is the same question the hiring manager would have asked silently before closing the tab.
Keep learning this
Paste this into any AI assistant. It turns the assistant into a tutor that tests you instead of just answering you.
Act as an experienced practitioner who is good at teaching. I have just learned using GitHub for portfolio work and writing a good README. Assume I am intelligent but relatively new to this — treat me as beginner level. Work through this in order, and wait for my reply at each step: 1. Ask me 5 questions that test whether I actually understood using GitHub for portfolio work and writing a good README. Do not reveal the answers yet. 2. After I answer, tell me which parts I got right, which I got wrong, and which I only half-understand. Explain only what I misunderstood — do not re-teach what I already know. 3. Give me one practical challenge based on something I could genuinely encounter at work or in daily life. Do not solve it for me. 4. Evaluate my solution the way an experienced person would judge it, including what a professional would have done differently. 5. Tell me what to learn next, and why that comes next. 6. Give me trustworthy sources for deeper study — prefer official documentation, primary research or standards bodies over blogs and videos. Rules for you: no buzzwords. No motivational filler. Say "I'm not certain" when you are not certain, and tell me which parts of your answer I should verify myself. Clearly separate facts from your recommendations and your opinions.
Become independent at this
Use this when you want a path from where you are to actually good, with checkpoints you can test yourself against.
I want to become independently capable at publishing and documenting work on GitHub — not permanently dependent on AI, tutorials or step-by-step guides. Design a progression for me with five stages: Beginner, Guided practice, Independent practice, Real-world application, Professional level. For each stage tell me: - what I must know - what I must be able to do without help - the mistakes people make at this stage - one practical challenge - one real project that would prove I reached this stage - one way I can test myself honestly Then tell me the signals that I am ready to move to the next stage, and the signals that I have skipped ahead too early. Keep the theory to the minimum I actually need. Focus on ability I can transfer to situations you and I have not discussed.