Developer README Template

Why the order matters

Most student READMEs open with installation instructions. That is the wrong order, and it is the single most common reason a good project gets passed over: nobody installs a project they do not yet care about.

A reviewer’s questions arrive in a predictable sequence. Follow it and the README does its job in about ninety seconds. Follow any other and the reader gives up somewhere around npm install.

The template

Copy this into README.md and fill it in. Delete any section that genuinely does not apply — an unedited template reads worse than no template.

# Project Name

One sentence describing what this does and who it is for.
Written for someone who has never heard of it.

**Live demo:** https://your-project.vercel.app
**Source:** https://github.com/you/project

![Screenshot or GIF of the app running](docs/demo.gif)

---

## The problem

Two or three sentences on the problem this solves and why you built it.
If it came from a real annoyance, say so — real motivation is more
convincing than an invented business case.

## Features

- **Feature name** — what a user can actually do, in one line
- **Feature name** — what a user can actually do, in one line
- **Feature name** — what a user can actually do, in one line

## Tech stack

| Layer     | Choice            | Why                                         |
| --------- | ----------------- | ------------------------------------------- |
| Front end | React, TypeScript | Type safety across a growing component tree |
| Back end  | Node.js, Express  | Familiar, and fast to build a REST API      |
| Database  | PostgreSQL        | Relational data with real constraints       |
| Hosting   | Vercel, Railway   | Free tier, deploys straight from git        |

## How it works

A short description of the architecture — the pieces, and how a request
flows through them. A diagram or a few lines of ASCII is plenty. Three
to five sentences beats three paragraphs.

```
Browser  ->  Next.js API route  ->  Postgres
                   |
                   +-> Redis cache (5 min TTL)
```

## Running it locally

### Requirements

- Node.js 20+
- PostgreSQL 15+

### Setup

```bash
git clone https://github.com/you/project.git
cd project
npm install
cp .env.example .env      # then fill in the values
npm run db:migrate
npm run dev
```

The app runs at http://localhost:3000.

### Environment variables

| Variable            | Purpose                    | Example                       |
| ------------------- | -------------------------- | ----------------------------- |
| `DATABASE_URL`    | Postgres connection string | `postgres://localhost/app` |
| `SESSION_SECRET`  | Signs session cookies      | any long random string        |

## Testing

```bash
npm test
```

Say what is covered and what is not. Being honest about the gaps reads
better than implying coverage you do not have.

## Technical decisions

The most valuable section in the whole file. Two or three decisions where
there was a real choice to make:

- **Chose X over Y because Z.** What the tradeoff was, and what it cost.
- **Chose X over Y because Z.** What the tradeoff was, and what it cost.

## What was hard

One or two genuine problems and how you solved them. Not "learning React
was hard" — something specific, like a race condition, an N+1 query, or a
deployment that only failed in production.

## What I would do differently

Two or three lines. Being able to critique your own work is a senior
habit and it is unusual on a junior portfolio.

## Roadmap

- [ ] The next thing you actually intend to build
- [ ] The one after that

## Licence

MIT — see [LICENSE](LICENSE).

Section-by-section

Title and one-liner

Write it for a person, not a search engine. “A shift-swapping tool for hospitality staff” tells a reviewer more than “A modern full-stack application built with the latest technologies”, which is a list of adjectives describing several thousand projects.

Demo link and screenshot

Above the fold, always. A GIF of the app being used is the highest-value single item in the file — record one with any screen recorder, trim to twenty or thirty seconds, show the main flow. For a CLI tool a terminal recording does the same job. For something that genuinely cannot be shown, three annotated screenshots.

The problem

This is where you show judgement rather than syntax. State the problem as a person having a bad time, not as a technology being absent. If the motivation was genuine annoyance, say so — it is more convincing than an invented business case and it explains why you finished.

Tech stack, with reasons

The table matters less than the “why” column. “Postgres because I needed transactions across three tables” is the kind of sentence that separates you from most candidates. You do not need a reason for every row — one or two genuine ones beat five invented ones.

How it works

Three to five sentences plus a diagram if it helps. A few lines of ASCII is completely acceptable and often clearer than a rendered image. The goal is to prove you understand your own architecture, not to write documentation for a team of twelve.

Running it locally

Then test the instructions from a clean clone. Make a new folder, clone into it, and follow your own steps exactly. This fails more often than people expect — a missing migration, a dependency you installed globally two months ago, a config file that only exists on your machine.

Technical decisions and what was hard

These are the two sections interviewers read back to you, which makes writing them interview preparation disguised as documentation. Two or three decisions where there was a genuine choice, each with the alternative you rejected. One or two specific problems — and specific is the whole game.

What I would do differently

Two or three lines. Being able to critique your own work is a senior habit, it is unusual on a junior portfolio, and it pre-empts the criticism a reviewer was about to make.

Before and after

The same project, documented two ways.

# recipe-app

## Installation

1. Clone the repo
2. Run npm install
3. Run npm start

## Technologies

- React
- Node.js
- MongoDB

# Recipe Cost Calculator

Works out what a meal actually costs per portion, accounting for
partial pack usage. Built for students cooking to a budget.

**Live:** https://recipe-cost.example.dev · **Source:** GitHub

![Adding ingredients and seeing cost per portion](docs/demo.gif)

## The problem

Cooking to a budget means knowing what a meal costs, but pack sizes
never match recipe quantities. Using 150g from a 500g bag is not
"one bag" of cost, and doing that arithmetic per ingredient by hand
is why nobody does it.

## Technical decisions

**Money stored as integer pence, never as a float.** Costs are
divided by portion counts and summed across ingredients, and
floating point drift showed up within about ten ingredients.

**Cost per portion is derived, never stored.** Ingredient prices
change; storing the computed cost meant every recipe silently went
stale. Deriving it is marginally slower and always correct.

Same code. The second version is roughly forty minutes of writing, and it is the difference between a project that gets skipped and one that gets asked about.

Quality check

• Someone outside your course can tell you what it does from the first two lines
• There is a live link, a GIF or screenshots near the top
• The setup instructions work from a clean clone — you actually tried it
• No placeholder text remains — search for “Project Name”, “Feature name” and “your-project”
• At least one real technical decision is explained, with the rejected alternative
• No secrets, keys or connection strings anywhere, including in example values
• Every link resolves
• It reads as though you wrote it

Do one properly rather than eight badly. A single excellent README on a pinned repository changes more than eight mediocre ones, because a reviewer reads the first one and forms their view there.