What belongs in the README you ship with a take-home coding assignment?

## The README is read before the code A take-home is reviewed asynchronously. The engineer who opens your repository usually has the brief, a scoring rubric, a short slot in their calendar, and nothing else. Anything they cannot reconstruct from your README - why a feature is missing, why you picked one shape over another, how to even start the thing - they will either guess at or count against you. That makes the README the highest-leverage file in the submission, and the one most candidates write last, in five minutes, at midnight. ## The sections that earn their space **What it does, in three or four lines.** Restate the problem as you understood it. If your reading of the brief drifted, this is the cheapest place for a reviewer to catch it, and it stops them from grading a correct solution to the wrong problem. **How to run it, on a clean machine.** Exact commands, in order: install, configure, seed any sample data, start, and run the tests. Verify them by cloning your own repository into an empty directory and following your own instructions literally. The most common way a genuinely strong submission scores badly is that it does not start for the reviewer, and a reviewer who cannot start it rarely reads much further. **Scope: what you built and what you deliberately did not.** List the parts of the brief you implemented and the parts you consciously skipped. The skipped list is the more interesting one: it is the only evidence a reviewer has that a gap was a decision rather than an accident. **Tradeoffs and known gaps.** Two or three short entries, each naming the alternative you rejected and the reason - throughput versus simplicity, an in-memory store versus a durable one, retry behaviour you stubbed. This is the section that separates a submission that works from a submission that shows an engineer thinking. **Time spent, honestly.** One line. It lets a reviewer calibrate everything above it, and honesty here is checkable against your commit history. ## A worked example A remote-first analytics scale-up sends a senior data engineer candidate a brief: ingest a directory of messy event files, deduplicate records, and expose a daily aggregate. The brief says it should take about six hours; the submission window is five days. One candidate ships the ingest-dedupe-aggregate path end to end, nine tests, and a README of roughly 350 words: four run commands verified on a fresh clone, a scope section saying the aggregate is computed on read rather than materialised because the brief emphasised correctness over latency, and a gaps section noting that malformed timestamps are dropped rather than quarantined, with quarantine named as the next step. Another candidate treats the five-day window as the budget, asks for an extension, and submits on day nine after roughly 31 hours: a dashboard, a container setup, and a plugin layer nobody asked for. The README is a feature list. The reviewer cannot tell which parts of the brief were understood, cannot tell what was cut, and cannot compare the work against the six hours everyone else spent. Both submissions run. Only one answers the question the brief asked. ## What does not belong An apology tour for unfinished work - state gaps neutrally instead. A restatement of your resume. A wall of architecture diagrams for a six-hour project. Long justifications for the parts you built past the brief; if you overbuilt, the README cannot rescue it, and the extra prose draws attention to the scoping problem rather than covering it. ## A practical habit Write the README as you go, not at the end. Every time you make a decision worth a sentence, put the sentence in the file immediately. At the end you are editing rather than reconstructing, and the tradeoffs you record are the ones you actually made instead of the ones you remember making.