How to Write a README for Your Capstone Project (Free Template)
You spent months building your capstone project. The code works, the database is complete, and the system looks great on your laptop. Then your adviser, a panelist, or a recruiter opens your GitHub repository and sees... nothing but a list of folders. No explanation, no screenshots, no idea how to run it. Most people will close the tab within a minute.
A good README fixes that. It is the front page of your project: the first file people read and often the only one. In this guide you will learn what to put in a README for a capstone or thesis project, the mistakes that make projects look unfinished, and a free Markdown template you can copy today.
What Is a README File?
A README is a text file in the main folder of a project that explains what the project is and how to use it. Most developers write it in Markdown and name it README.md. GitHub, GitLab and Bitbucket automatically display it below the file list of your repository, so it works like a landing page.
Markdown is easy to learn. A line starting with # becomes a heading, **text** becomes bold, a line starting with - becomes a bullet, and text between three backticks becomes a code block. You can preview it in VS Code by opening the file and pressing Ctrl+Shift+V (Cmd+Shift+V on Mac).
Why Your Capstone Project Needs a Good README
- Your panel and adviser can run your system. Clear installation steps mean fewer "it doesn't work on my computer" moments during checking.
- Recruiters actually look at it. When you put a GitHub link on your resume, the README is your first impression. It shows that you can communicate, not just code.
- Future you will thank you. Six months after graduation you will forget the default password, the database name, and which PHP version you used.
- Your groupmates stay on the same page. A shared setup guide saves hours of "how do I run this again?" messages.
The 10 Sections Every Capstone README Should Have
1. Project Title and One-Sentence Description
Say what the system does and who it is for in one sentence. "A web-based enrollment system for senior high schools that lets students pre-register online and lets the registrar approve them" is far better than "Enrollment System."
2. Screenshots
People decide in seconds whether a project looks interesting, and screenshots do the convincing for you. Add two to four images of your most important screens, such as the dashboard, a main form and a report. Save them in a folder like docs/screenshots/ and link them with relative paths so they show up on GitHub.
3. Features
Use a short bullet list grouped by user role: what the admin can do, what the staff can do, what the student or customer can do. This also helps panelists see the scope of your work at a glance.
4. Tech Stack
List the language and version, framework, database, and important libraries. For example: PHP 8.3, MySQL 8, Bootstrap 5, Chart.js. Versions matter, because a project built on one version may break on another.
5. Requirements
Everything someone needs to install before running your project: XAMPP or Laragon, Node.js, Python, Composer, a specific browser, and so on.
6. Installation Steps
This is the most important section. Write numbered steps that a classmate could follow without asking you anything: where to copy the folder, how to import the database, which config file to edit, which command to run, and which URL to open. Then test your own steps on a different computer. If you skip a step, you will find out during your defense.
7. Default Accounts
List the sample usernames and passwords for each role so testers can log in right away. Remind readers to change them in a real deployment.
8. Project Structure and Database
A short folder tree with one-line comments helps readers find their way around. Add a list of your main database tables, or include an ERD image if you have one.
9. Known Issues and Future Improvements
Being honest about limitations looks professional, not weak. Panelists often ask "what would you improve?", so you will already have a good answer written down.
10. Team, Credits and License
Name the members and their roles, thank your adviser, and credit any templates, icons or libraries you used. If you want others to reuse your code, add a license such as MIT. GitHub can add a LICENSE file for you when you create the repository.
A Free README Template for Capstone Projects
Copy this into a file named README.md in the root folder of your project, then replace the parts in square brackets:
# [Project Name]
[One sentence: what the system does and who it is for.]
## Features
**Admin**
- [Manage users and roles]
- [View reports and dashboard]
**Staff / Student / Customer**
- [Main thing this user can do]
- [Another feature]
## Tech Stack
- [Language and version, e.g. PHP 8.3]
- [Database, e.g. MySQL 8 / MariaDB]
- [Framework or libraries, e.g. Bootstrap 5, Chart.js]
## Requirements
- [e.g. XAMPP 8.2 or newer]
- [e.g. Composer / Node.js 24 / Python 3.13]
## Installation
1. Clone or download this repository.
2. Copy the project folder to `[C:\xampp\htdocs\]`.
3. Create a database named `[db_name]` and import `database/[file].sql`.
4. Copy `.env.example` to `.env` (or edit `config.php`) and set your database login.
5. Open `http://localhost/[project-folder]` in your browser.
## Default Accounts
| Role | Username | Password |
|-------|----------|------------|
| Admin | admin | [admin123] |
| Staff | staff | [staff123] |
> Change these passwords before using the system in a real environment.
## Project Structure
```
[project-folder]/
├── config.php # database settings
├── database/ # SQL file
├── assets/ # CSS, JS and images
└── ...
```
## Known Issues / Future Improvements
- [Something that does not work perfectly yet]
- [A feature you would add with more time]
## Team
- [Name] - [Role, e.g. Project Manager / Back-end Developer]
- [Name] - [Role]
Adviser: [Name]
## License
[MIT License / For educational purposes only]
Common README Mistakes to Avoid
- Committing real passwords and API keys. Never put real database passwords, email passwords or API keys in your README or code. Commit a
.env.examplefile with placeholder values and add the real.envto.gitignore. Leaked keys are actively hunted by attackers, as the recent wave of stolen AI keys showed. - "Just run it." Steps that only work on your laptop are not installation steps. Mention every tool, version and setting.
- Forgetting the database. Many school projects are uploaded without the
.sqlfile, which makes them impossible to run. Export it and say where it is. - Broken images. Using a path like
C:\Users\Juan\Desktop\screenshot.pngonly works on your computer. Use relative paths inside the repository. - Outdated instructions. If you switched from MySQLi to PDO or renamed the database, update the README too. A wrong README is worse than a short one.
- A wall of text. Use headings, lists, tables and code blocks. People scan READMEs; they rarely read them top to bottom.
Bonus Tips That Make Your Project Stand Out
- Add a short demo GIF or video link. A 20-second clip of the main workflow shows more than paragraphs of text.
- Include a "How It Works" section with one or two sentences about your main algorithm or business rule, such as how grades are computed or how the queue is ordered. Panelists love this.
- Write in simple English. Short sentences are easier to read for everyone, including non-technical clients.
- Pin the repository on your GitHub profile so recruiters see it first.
Conclusion
A README takes one or two hours to write, but it changes how people see months of your work. Start with the template above, fill in the installation steps carefully, add a few screenshots, and test the instructions on a friend's computer. When your panel or a future employer opens your repository, they will immediately know what you built, how to run it, and that you care about the details.
Looking for a project to practice on? Browse the free source code projects here on SourceCodester, try writing a README for one of them, and see how much clearer the project becomes. Happy coding!