What belongs in a take-home README, and why does a reviewer open it first?
answer
- what does a reviewer open first?
- the artifact that frames the code
- decisions, not install instructions
- record what was cut and why
- known limits plus concrete production next steps
basics
~20 sThe README is the tradeoff record, not install instructions. It should state how to run everything, the approach chosen and what it was chosen over, what was deliberately cut and why, known limitations, and what a production version would add.
solid answer
~50 sA reviewer opens the README first because it tells them how to read everything else — which parts are deliberate, which are scoped out, and where to look for the interesting decision. Five things earn their place: one command that runs the program and one that runs the tests; the approach and the alternative you rejected, with the reason; what you cut against the time cap; the known limitations, including any case you know is unhandled; and the two or three things a production version would add. Keep it short and factual — a page of prose is a page the reviewer will skim. The register matters as much as the content: this is a decision record, not an apology. Naming an unhandled case does not expose weakness; it converts a gap the reviewer would have found anyway into evidence that you knew about it and chose deliberately.
go deeper
Recall the five sections worth writing: how to run it and its tests, the approach taken, what was cut, known limitations, and what production would add. Keep each one to a line or two.
Explain why the note changes the reading of identical code: it separates deliberate scope from oversight, which the code itself cannot signal. Be ready to draft the approach paragraph naming the alternative you rejected.
Demonstrate the decision-record register — factual, specific, unapologetic — and defend naming a known unhandled case as a strength. Show that your cuts and your limitations tie back to the stated budget.
Own the argument that written tradeoff records are the transferable signal here: the same writing you want on real changes. Be able to say what an unattended exercise can and cannot evidence about an engineer's judgment.
## The artifact that frames the code In an unattended exercise you are not in the room, so the writing does the job your voice does in a live round. The README is where that happens, and it is almost always the first thing opened — before the entry point, before the tests. Reviewers read it first because it answers the question that governs their whole reading: *which parts of this submission are decisions, and which are accidents?* Without that frame, everything the reviewer notices is ambiguous. A missing case might be an oversight or a documented scope call. A simple structure might be pragmatic restraint or a candidate who does not know what a seam is. A slow aggregation might be a considered choice at the stated data size or an unnoticed cost. The code cannot disambiguate itself; the README can, in two sentences per item. ### What earns its place **How to run it.** One command for the program, one for the tests, and the assumed input shape. Anything that costs the reviewer ten minutes of setup archaeology costs you more than the time you saved by omitting it. **The approach and the road not taken.** One short paragraph: what you built, and the alternative you rejected with the reason. On a catalog import that might be — a single pass accumulating by SKU into a keyed total, chosen over sorting the feed first because the input has no useful order and the keyed pass avoids the extra `O(n log n)`. This is the paragraph that most distinguishes submissions, because it shows the decision rather than its residue. **What was cut, and why.** The scope calls, tied to the stated budget. *Only one input shape supported; the alternate format was cut to keep the core path tested within the cap.* Each cut costs one line and buys the reviewer certainty that it was intentional. **Known limitations.** The cases you know are unhandled or partially handled — a malformed row aborting the batch rather than being rejected individually, say. Candidates fear this section, believing it advertises weakness. It does the opposite: the reviewer will find those cases regardless, and the only variable is whether they find them alongside evidence that you knew. Naming a limitation converts a defect into a demonstrated boundary of scope. **What production would add.** Two or three concrete items — durable handling of partial failures, observability on reject rates, a real schema for the feed. Concrete is the operative word; *would add proper error handling and logging* is a phrase, not a plan. ### What does not belong Apology, at any length. *Sorry this is rough, I was short on time* converts a scoping decision into an admission and invites the reviewer to grade against the imagined full version rather than the one you shipped. A tour of the file layout. The reviewer can see the files; describing them consumes their attention without adding information. A restatement of the problem. They wrote it. Generic future work with no specifics, and long essays generally — a README that runs pages will be skimmed, which means the parts you most needed read are the parts most likely to be missed. Short, factual, sectioned, scannable. ### Register: a decision record, not a confession The strongest README reads like a well-written change description from a senior colleague: here is what it does, here is what I chose and why, here is what I did not do, here is what I would do next. It is calm, specific, and unhedged. That register is itself a signal — it is the same writing the reviewer would want on a real change, which is precisely what an unattended exercise is trying to sample. ### The misconception *The README is a formality; the code speaks for itself.* Code states what it does and is entirely silent about what it deliberately does not do, and in an unattended review that silence is read as absence of thought rather than absence of scope. Two submissions with identical code and different notes are not graded the same — the one that names its cuts and limits reads as a deliberate delivery, and the one without reads as whatever the reviewer was already inclined to assume.
- Does listing known limitations hurt you by advertising defects?No — the reviewer finds those cases either way; the only variable is whether they find them alongside evidence that you knew. A named limitation reads as a boundary of scope you chose; the same gap unnamed reads as an oversight. The one caveat is register: state it factually in a line, without apology or hedging.
- What length should a take-home README be?Short enough to be read rather than skimmed — typically well under a page, in scannable sections. Reviewers work under time pressure too, and a long document buries the two paragraphs that mattered: the approach with its rejected alternative, and the list of deliberate cuts. Cut the file tour and the problem restatement to make room.
- Which single section most differentiates submissions?The approach paragraph naming the alternative you rejected and why. Every submission shows the residue of a decision in its code; almost none shows the decision itself. One or two sentences — a keyed single pass chosen over sorting first because the feed has no useful order — demonstrate judgment that the code alone cannot evidence.
It is the change description on a pull request, not the packaging insert: the reviewer reads it to know what they are looking at before they look.
saying these in an interview costs you the question
- The README is just install and run instructions
- Naming what I skipped makes me look weak
- Opens with an apology for the state of the code
- Tours the file layout the reviewer can already see
- Future work listed as vague phrases, not concrete items
- Assumes the code speaks for itself about what was cut