# Developer README Template > A copy-and-fill README structure that answers a reviewer's questions in the order they actually ask them. **What this is:** A complete README skeleton with guidance on what belongs in each section, plus the quality check to run before you call one finished. **Time needed:** 30–45 minutes per project **You end up with:** A README that lets a stranger understand, run and judge your project without asking you anything. --- ## Why the order matters Most student READMEs open with installation instructions. That is the wrong order: nobody installs a project they do not yet care about. A reviewer's questions arrive in a predictable sequence — what is this, can I see it working, what is it built with, how does it work, can I run it, what did you learn — and the template below simply follows that sequence. Fill in every section. If one genuinely does not apply, delete it rather than leaving the placeholder in; an unedited template reads worse than no template at all. ## The template `README.md` ````markdown # 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 guidance **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". **Demo link and screenshot.** Put these above the fold. A GIF of the app being used is the highest-value thing in the file — record one with any screen recorder and convert it. For a CLI tool, a terminal recording does the same job. **The problem.** This is where you show judgement rather than syntax. Reviewers are trying to work out whether you can identify a problem worth solving, not only whether you can type. **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. **How it works.** Keep it short. The goal is to prove you understand your own architecture, not to write documentation for a team of twelve. **Technical decisions and what was hard.** These are the two sections interviewers read back to you. Writing them down is interview preparation disguised as documentation. ## README quality check Run this before you consider a README finished. - [ ] **Someone who has never seen the project understands it from the first two lines** Give it to a friend outside your course and ask them to tell you what it does. - [ ] **There is visual proof it works** A live URL, a GIF or screenshots. At least one of the three, near the top. - [ ] **The setup instructions work from a clean clone** Actually try it in a new folder. This is the most common failure by a distance. - [ ] **No placeholder text from the template remains** Search the file for "Project Name", "Feature name" and "your-project". - [ ] **At least one real technical decision is explained** With the alternative you rejected and the reason you rejected it. - [ ] **No secrets, keys or connection strings appear anywhere** Including in the example values, and including in the commit history. - [ ] **Every link resolves** Demo, licence, images, related repositories. - [ ] **It reads as though you wrote it** If you drafted it with AI, rewrite the problem, decisions and what-was-hard sections in your own words. Those are the parts you will be asked about out loud. > **One README is enough to start** > > Do not try to rewrite documentation for eight repositories in a weekend. Do one properly on your strongest project, use it as the model, then work down the list. A single excellent README on a pinned repository changes more than eight mediocre ones. --- Part of the free Developer Portfolio Toolkit — https://devproof.app/free-developer-portfolio-toolkit Free to use, copy and adapt for your own portfolio.