One job
Your README has one job: help a stranger understand and run your project.
Assume the reader is a recruiter, judge, or senior student. They will not DM you for missing steps.
What to include
A good hackathon README is not long. It is complete.
Put the most useful information near the top, because people scan on phones and laptops.
- Name the project and the problem it solves.
- Show the tech stack, like React, Node.js, Flask, Firebase, or MongoDB.
- Explain the main features in 3 to 6 bullets.
- Give exact setup commands.
- List required environment variables without sharing secrets.
- Add screenshots or a short demo link if you have one.
Common README mistake
Beginners write only: “Run npm install and npm start.” That is not enough for a stranger.
Mention the required Node, Python, Java, or database version if your project depends on it. If an API key is needed, say where to add it and what name to use.
README skeleton
Use this structure. Replace the details with your project.
Do not paste fake commands. Only include commands you have tested.
# Campus Mess Feedback
A web app for college students to submit mess food feedback and for admins to view trends.
## Features
- Student feedback form
- Admin dashboard
- Daily rating summary
- Firebase authentication
## Tech stack
- React
- Firebase
- Tailwind CSS
## Screenshots
Add screenshots here.
## Setup
1. Clone the repo
```bash
git clone https://github.com/your-username/campus-mess-feedback.git
cd campus-mess-feedback
```
2. Install dependencies
```bash
npm install
```
3. Create a `.env` file
```bash
VITE_FIREBASE_API_KEY=your_key_here
VITE_FIREBASE_AUTH_DOMAIN=your_auth_domain_here
```
4. Start the app
```bash
npm run dev
```
Open the local URL shown in the terminal.
## Demo login
Student: [email protected] / password123
Admin: [email protected] / password123
## What I learned
- Built protected routes
- Connected Firebase auth
- Designed a simple dashboard for real usersUse AI carefully
Ask ChatGPT, Gemini, or Claude to draft the README from your code and package files. This saves time, but you must verify it.
Check every command, every env variable name, and every feature claim. AI often adds features you did not build or misses setup steps.
Prompt:
Read this project structure, package.json, and main files. Draft a beginner-friendly README for GitHub. Include project summary, features, tech stack, setup commands, environment variables, and how to run locally. Do not invent features.
Then paste your package.json and folder structure.Test like a stranger
Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.
0 of 5 done
git clone https://github.com/your-username/your-repo.git
cd your-repoDo this now
Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.
0 of 5 done
git add README.md .env.example
git commit -m "Add clear setup instructions to README"