Writing Effective Project DescriptionsLesson 4.2

How to write a README that makes developers trust your project

README structure, badges, installation instructions, env variables, screenshots, contributing section, license, live demo link, tech stack table

The README Is Your Project's Front Door

Any developer who finds your project on GitHub decides within 10 seconds whether it is worth exploring further. A README with clear setup instructions, a live demo link, and a screenshot makes that decision easy.

Required README Sections

# Project Name

> One-line description of what it does and who it's for.

[Live Demo](https://your-demo-url.com) | [GitHub](https://github.com/you/repo)

## Tech Stack
| Layer | Technology |
|-------|------------|
| Frontend | React, Tailwind CSS |
| Backend | Node.js, Express |
| Database | PostgreSQL |

## Getting Started
```bash
git clone https://github.com/you/repo.git
cd repo
npm install
cp .env.example .env   # Add your env vars
npm run dev
```

## Environment Variables
| Variable | Description |
|----------|-------------|
| DATABASE_URL | PostgreSQL connection string |
| JWT_SECRET | Secret key for auth tokens |

## Screenshots
![Dashboard](assets/screenshot.png)

## License
MIT

The .env.example file is critical — never commit a real .env, but always commit the example with all required variable names and placeholder values. A developer who cannot run your app locally in under 5 minutes will close the tab.