# The README Template That Saves Me 2 Hours Per Project
By Govind Bajaj · 2024

Tags: documentation, readme, methodology, open-source, workflow
I open-sourced a README template after realizing I was rewriting the same sections for every project. 47 stars later, it's clear I'm not the only one who needed this.
I open-sourced a README template after realizing I was rewriting the same sections for every project.

Forty-seven stars later, it is clear I am not the only one who needed this.

A good README is not documentation — it is a sales pitch for your code. It tells a developer whether this project solves their problem in under thirty seconds. Then it gets them running locally in under five minutes.

Here is the template I use, section by section, with explanations of why each matters.

## Section 1: One-Line Description

The first line of the README is the most important. It should complete this sentence: "This project is a \____\_ that \____\_."

Bad: "A web application built with Next.js." Good: "An e-commerce platform for Ayurvedic products with Razorpay payments and real-time inventory."

The bad example describes the technology. The good example describes the value. Developers scanning GitHub want to know what it does, not what it is built with.

## Section 2: Screenshot or Demo

A picture is worth a thousand words. A GIF or screenshot immediately shows what the project looks like.

If it is a web app, include a screenshot of the main page. If it is an API, include a code example of the response. If it is a CLI tool, show the output.

```markdown
![Sans Herbals Homepage](/docs/screenshot-home.png)
```

## Section 3: Features (The "Why This" Section)

List 3-5 features that differentiate this project. Not every feature — the ones that matter.

```markdown
## Features

- UPI payments via Razorpay with automatic retry on failure
- Real-time inventory updates across all admin dashboards
- SEO-optimized product pages with JSON-LD structured data
- Image optimization and CDN delivery via Cloudinary
- Role-based access control (admin, editor, viewer)
```

## Section 4: Tech Stack

List the core technologies. Not every dependency — the major ones.

```markdown
## Tech Stack

- **Framework**: Next.js 15 (App Router)
- **Database**: MongoDB with Mongoose
- **Auth**: NextAuth v5
- **Payments**: Razorpay
- **Styling**: Tailwind CSS
- **Deployment**: Vercel
```

## Section 5: Getting Started

This is the most important practical section. Get the user from clone to running in as few steps as possible.

```markdown
## Getting Started

### Prerequisites

- Node.js 20+
- MongoDB (local or Atlas)
- Razorpay test account

### Installation

```bash
# Clone the repository
git clone https://github.com/username/repo.git
cd repo

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your credentials

# Run the development server
npm run dev
```

```

## Section 6: Environment Variables

List every environment variable the application needs. This prevents the "why is it crashing?" issues.

```markdown
## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `MONGODB_URI` | MongoDB connection string | Yes |
| `RAZORPAY_KEY_ID` | Razorpay API key | Yes |
| `NEXTAUTH_SECRET` | Random string for JWT signing | Yes |
| `PUSHER_APP_ID` | Pusher app ID (for real-time) | No |
```

## Section 7: Project Structure

A brief overview of the directory structure helps developers find what they are looking for.

```markdown
## Project Structure
```

├── app/ # Next.js App Router ├── components/ # React components ├── lib/ # Utility functions and configs ├── models/ # Mongoose schemas ├── public/ # Static assets └── types/ # TypeScript types

```
```

## What to Skip

Do not include: API documentation (use a docs site or Postman collection), detailed architecture decisions (use ADRs in the repo), changelog (use GitHub releases), or contributor guidelines (use CONTRIBUTING.md).

## Takeaways

- A README is a sales pitch, not documentation — show value first
- One-line description should describe what it does, not what it is built with
- Include a screenshot or demo GIF — visual proof beats text descriptions
- Getting Started should go from clone to running in under 5 minutes
- List all environment variables — prevents silent crashes
- Features section should differentiate, not enumerate
- Skip detailed API docs and architecture — link to dedicated documentation
- This template saves 2 hours per project because the structure is already decided