How Engineers Write a README
12 Senior Habits
A README isn't "a polite document for strangers." It's "a postcard of your engineering discipline." When a recruiter clicks into your GitHub, the first thing they see is the README ─ and in under 30 seconds they can tell whether you're a junior or a senior. This post breaks it down for you ─ how seniors write a README, plus a complete template you can copy.
Why a README matters more than you think
Picture a scenario:
You send your résumé to a company, the recruiter clicks the GitHub link on it, and they open one of your recent repos at random.
- No README ─ the recruiter scrolls for 3 seconds and closes the tab
- A one-line README ─ the recruiter can't tell what you built and closes the tab
- A proper README ─ the recruiter reads for 30 seconds, sees what problem you're solving and what tech you used, and decides to spend more time on your code
The gap isn't "strong vs. weak code" ─ it's "whether you turned your work into something other people can understand."
Plenty of people are technically strong.
People who are both technically strong and able to make others understand what they built are rare.
That's the difference between a senior and a junior.
12 habits seniors follow when writing a README
01 First line: say what it is in one sentence
Don't write "This is a project I made for fun."
Write "one sentence that makes the problem + solution + audience clear":
# Mentry CLI A command-line tool that audits your Next.js project for production-readiness ─ designed for solo developers shipping their first SaaS.
That one sentence should answer 3 questions:
- What problem does it solve?
- How does it solve it?
- Who is it for?
02 Drop in a screenshot or demo GIF
Humans process images about 60 times faster than text (the rough consensus in cognitive science).
In the very first block of every README, put one of these:
- UI project → a screenshot (ideally light + dark mode)
- CLI project → a terminal recording (use asciinema, agg)
- API project → a screenshot of a curl example / a flow diagram
- Library → a screenshot of a code usage example
A README with no image = a book with no cover. Most people won't open it.
03 A badge row ─ but don't cram it
Plenty of people cram in 15 badges ─ build / test / coverage / dependency / license / npm / downloads / discord / twitter and on and on.
Seniors usually keep just the 3 to 5 that matter:
  
The principle ─ a badge should carry a signal, not be decoration.
04 A 5-minute quick start block
This is the most important block for telling "software vs. code" apart.
## Quick Start ```bash git clone https://github.com/user/repo.git cd repo cp .env.example .env npm install npm run dev ``` Open http://localhost:3000 ─ should see the welcome page.
Key points:
- The commands should be "copy-pasteable as-is," not written as prose
- Mention the
.env.example─ don't assume the reader already knows - The last line should say "what you should see," so people know whether it ran successfully
05 Spell out the prerequisites
Don't assume the reader has the same setup you do.
## Prerequisites - Node.js 20+ - pnpm 9+ (or npm 10+) - PostgreSQL 15+ (or use the Docker setup below) - OpenAI API key (free tier works for testing)
Seniors list the "minimum version" plus "whether there's a fallback."
06 Explain configuration with a table
Environment variables, config options, CLI flags ─ all of it in a table.
## Environment Variables | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `DATABASE_URL` | ✅ | - | PostgreSQL connection string | | `OPENAI_API_KEY` | ✅ | - | Your OpenAI API key | | `PORT` | ❌ | `3000` | Server port | | `LOG_LEVEL` | ❌ | `info` | One of: debug, info, warn, error |
A table is 5 times easier to read than a bullet list.
07 Use code blocks, don't write prose
What not to do:
"To install, run npm install in the root directory, then create a .env file with your API key, and finally run npm start to launch the server on port 3000."
How a senior writes it:
```bash npm install cp .env.example .env # add your API key npm start # server runs on :3000 ```
The visual information density differs by 5x.
08 Explain your tech choices with "Why X over Y"
This is the biggest difference between a junior's and a senior's README.
Junior README: lists the tech stack.
Senior README: lists the tech stack + why.
## Tech Stack - **Next.js 15** ─ App Router + Server Actions, optimized for low-traffic SaaS - **Drizzle ORM** ─ chosen over Prisma for better edge runtime compatibility - **Cloudflare Pages** ─ free tier handles up to 100K req/day, no cold start - **Stripe** ─ for subscription billing (was Lemon Squeezy, switched for tax handling)
Those "whys" convey one thing ─ you didn't pick tools at random; you thought through the trade-offs. A recruiter or interviewer will bump you up a level.
09 Add a "Project Structure" block
A simple directory layout, as an ASCII tree:
## Project Structure ``` src/ ├── app/ # Next.js App Router pages ├── components/ # Shared React components ├── lib/ │ ├── db/ # Drizzle schema & queries │ ├── auth/ # NextAuth config │ └── ai/ # OpenAI wrappers ├── tests/ # Vitest unit tests └── e2e/ # Playwright E2E tests ```
This block lets a newcomer skim it in 30 seconds and know "I need to change X ─ where do I go to find it."
10 Write a "How to Contribute" section ─ even for a personal project
This is the small detail that leaves recruiters impressed.
## Contributing PRs welcome. Before submitting: 1. Run `npm test` ─ all tests should pass 2. Run `npm run lint` ─ no errors 3. Update relevant docs if you changed behavior 4. Write a clear PR description (the "why", not just "what")
Having this section ─ it shows you've thought about "how others work with me," not just "how I write my own code."
11 Show your thinking with a "Roadmap"
List 3 to 5 things you know about but haven't done yet:
## Roadmap - [x] CSV export - [x] User authentication - [ ] Multi-tenancy (planned Q3) - [ ] Webhook support (depends on user demand) - [ ] OAuth login (Google, GitHub) See [Issues](https://github.com/user/repo/issues) for detailed planning.
A roadmap shows you know what's missing right now and what you want to build ─ that's a hallmark of a senior.
12 End with a License + acknowledgements
## License MIT ─ see [LICENSE](./LICENSE) ## Acknowledgements - Inspired by [neetcode.io](https://neetcode.io) for the topic structure - Logo by [@designer-handle](https://twitter.com/designer-handle) - Built during the 100-day [Mentry Build in Public](https://mentry.dev) journey
Acknowledgements look like a small thing, but they actually convey 2 signals:
- You're not a lone wolf ─ you credit the people who came before you
- You respect intellectual property
When a recruiter or open source maintainer sees acknowledgements, it pushes their impression of you straight to "professional."
The full README template (copy it straight in)
Below is the complete template that pulls all 12 points together. You can copy it as the starting point for your new project's README.md:
# Project Name > One-sentence pitch ─ what it does, for whom, and the unique angle.     ## ✨ Why This Exists Briefly: what problem you saw, why existing solutions didn't fit, what your approach is. ## 🚀 Quick Start ```bash git clone https://github.com/user/repo.git cd repo cp .env.example .env # fill in API keys npm install npm run dev ``` Open http://localhost:3000 ─ should see the welcome page. ## 📦 Prerequisites - Node.js 20+ - pnpm 9+ (or npm 10+) - PostgreSQL 15+ (or use included Docker setup) ## ⚙️ Configuration | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `DATABASE_URL` | ✅ | - | PostgreSQL connection string | | `API_KEY` | ✅ | - | Your service API key | | `PORT` | ❌ | `3000` | Server port | ## 🏗️ Tech Stack - **Next.js 15** ─ App Router for incremental adoption - **Drizzle ORM** ─ chosen for edge runtime compatibility - **Tailwind CSS** ─ utility-first, easy to customize - **Vitest** ─ faster than Jest for our use case ## 📁 Project Structure ``` src/ ├── app/ # Next.js routes ├── components/ # Shared UI ├── lib/ # Business logic ├── tests/ # Unit tests └── e2e/ # E2E tests ``` ## 🧪 Testing ```bash npm test # unit tests npm run test:e2e # end-to-end npm run test:watch # watch mode ``` ## 🤝 Contributing PRs welcome! Before submitting: 1. Run `npm test` ─ all tests pass 2. Run `npm run lint` ─ no errors 3. Update relevant docs 4. Write a clear PR description (why, not just what) ## 🗺️ Roadmap - [x] Core feature A - [x] Core feature B - [ ] Multi-tenancy (planned next quarter) - [ ] Webhook support ## 📜 License MIT ─ see [LICENSE](./LICENSE) ## 🙏 Acknowledgements - Inspired by [project-name](https://example.com) - Built during [Project Name](https://example.com) journey
One last reminder
A well-written README can affect your next interview 10 times more than 100 lines of commits.
Because it's the first file your interviewer, the recruiter, your future teammates, and future you will read.
This week, spend 30 minutes going back and rewriting the README of the single most representative repo on your GitHub. Next time someone clicks into it, the person they see will be a different you.
Want someone to review the whole front face of your GitHub?
A 30-minute 1-on-1 consultation, NT$1,500 ─ I'll go through your README, project structure, commit history, and overall presentation, and give you a concrete list of what to change.