Say you’ve picked bus-delays, a script that reports weekly delays by bus route, to lead your portfolio. A hiring manager clicks the link, and this is the first screen they see:
# bus-delays
## Installation
1. Clone the repo
2. pip install -r requirements.txt
3. Copy .env.example to .env and add your API key
## Usage
python main.py --start 2026-01-01 --end 2026-03-31
Give yourself thirty seconds with it, just like the hiring manager. What do you know about the project now? And what do you know about the person who built it?
Whoops! You know that it needs an API key and takes two dates, and that’s about it.
This README addresses someone who has already decided to use the project. A reviewer hasn’t decided anything yet. They’re still wondering what this thing is and why anyone would want it.
Two Readers, Two Time Budgets
A project write-up serves two readers. The first has thirty seconds and wants to know what the project is, who it’s for, what it looks like, and how to run it. The second has ten minutes and wants to understand your thinking, such as why you chose this problem, which decisions you made and what they cost, what broke, and what you’d do next.
