Tech Portfolio: How to Write a GitHub README That Shows What You Built

Last updated: 7 October 2026

Tech Portfolio: How to Write a GitHub README That Shows What You Built

A README in a tech portfolio should help a reader understand what problem the project solves, how to use it, and which parts the student was responsible for, followed by the key decisions, testing and limits met along the way, so the code and the explanation tell the same story. GitHub describes the README as the place to communicate important information about a project, and it is often the first thing visitors see (GitHub Docs).

Start with the problem, not a list of tools

“Built with Python, JavaScript and a database” lists tools but not purpose. Start with the problem, the user and the outcome, for example: “A club equipment-loan tracker that shows members which items are available and helps organisers see what has not been returned.” (A hypothetical example for illustration, not a real student project.)

What a portfolio README should include

SectionWhat to writeEvidence that helps
Problem and usersWho has what problem, and the scope you choseOne usage scenario
What it doesFeatures that already workScreenshots or a demo video with captions
How to try itSteps and any sample data neededCommands or steps you have tested
Your roleWhat you built alone and what you built with othersA list of responsibilities that matches the work
DecisionsWhy you chose one approach over anotherOptions and constraints you considered
Testing and bugsWhat you tested, what you found, how you fixed itA test table or bug log
Limits and next stepsWhat it does not handle yet and whyA realistic next iteration

Example: describe testing beyond “it works”

ScenarioExpected resultWhat to check
Borrow an available itemStatus changes to on loanThe loan record matches the item
Borrow an item already on loanNo duplicate loan is createdThe user understands why
Return an itemStatus returns to availableThe outstanding list updates
Submit incomplete detailsThe form flags what is missingNo ambiguous record is saved

In a real README, record what actually happened, not only what you expected. If items could be borrowed twice, explain the cause, the fix and the result after retesting; that shows your thinking far better than “I can debug”.

Make your own contribution clear

For group projects, list your real responsibilities, such as data design, validation logic or the interface. Separate libraries, sample code and AI coding tools from what you designed and wrote yourself. Commit counts alone do not show quality or role; explain how you understood the system, adapted it to the problem and checked the results.

Ask someone else to read it

Ask someone who has not seen the project whether they can say who it helps and what it does, where to start, which parts you built, the most important decision, and what you would build next. If they cannot, add an example or reorder the sections rather than adding more jargon.

Want a study plan that fits your child?

Tell us the curriculum, year group, exam date (if any) and goal. Our academic team will suggest a starting plan, 1-on-1 at our Bangkok centre or online.

Learn 1-on-1: Python for Beginners

Frequently Asked Questions

Does a project need to be big to go in a tech portfolio?

Size alone does not show quality. Choose a scope you can finish and explain in detail, and check the portfolio format each course accepts.

I already have screenshots. Do I still need a README?

Yes. Screenshots show what it looks like; the README explains context, how to use it and the decisions behind it.

Will every university look at my GitHub?

Do not assume so. Check how each course accepts portfolio work, and prepare a short written explanation in case you need to submit a document or discuss it at interview.

Max Academia’s 1-on-1 Tech Portfolio Programme helps students scope and develop projects around their level and application goals. See also which projects to include in a tech portfolio.

Share the Post: