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
| Section | What to write | Evidence that helps |
|---|---|---|
| Problem and users | Who has what problem, and the scope you chose | One usage scenario |
| What it does | Features that already work | Screenshots or a demo video with captions |
| How to try it | Steps and any sample data needed | Commands or steps you have tested |
| Your role | What you built alone and what you built with others | A list of responsibilities that matches the work |
| Decisions | Why you chose one approach over another | Options and constraints you considered |
| Testing and bugs | What you tested, what you found, how you fixed it | A test table or bug log |
| Limits and next steps | What it does not handle yet and why | A realistic next iteration |
Example: describe testing beyond “it works”
| Scenario | Expected result | What to check |
|---|---|---|
| Borrow an available item | Status changes to on loan | The loan record matches the item |
| Borrow an item already on loan | No duplicate loan is created | The user understands why |
| Return an item | Status returns to available | The outstanding list updates |
| Submit incomplete details | The form flags what is missing | No 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.
Related articles
- Scratch or Python: Which Should Your Child Learn First?
- Learning Python for the First Time: Where to Start and What Your First Project Should Be
- Tech Portfolio for Computer Science Applications: Which Projects Should You Include?
Learn 1-on-1: Python for Beginners
Frequently Asked Questions
Size alone does not show quality. Choose a scope you can finish and explain in detail, and check the portfolio format each course accepts.
Yes. Screenshots show what it looks like; the README explains context, how to use it and the decisions behind it.
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.

