How To Read

The track budgets ~183 hours of primary sources across 34 months and, until now, assumed you knew how to extract from them. That assumption is wrong for most engineers and specifically risky for you: you described yourself as spreading attention and staying in consumption mode, and reading is the activity that mode is made of.

This page is the protocol. It is short on theory and long on what to do with your hands.

Table of Contents

• The Core Problem
• The Three-Pass Method
• Reading After Building, Not Before
• The Extraction Note
• Reading Code
• When To Stop
• Worked Example — Raft §5.4.2
• Worked Example — Reading LevelDB
• The Anti-Patterns
• Budget Discipline
• References

The Core Problem

A systems paper is not written to teach you. It is written to convince a program committee that a contribution is novel and correct. Consequently:

• The contribution is usually one idea, wrapped in twenty pages of context, evaluation, and related work.
• The evaluation section is advocacy. Benchmarks are chosen by the authors.
• The hardest part is often one paragraph — and it is rarely flagged.
• The related-work section is the most useful part for you, and almost nobody reads it, because it is a map of what has already been tried.

So reading linearly, at uniform speed, from abstract to references, is the wrong algorithm. It spends most of your attention on the parts written for someone else.

And the deeper problem: reading produces recognition, which feels exactly like understanding from the inside and is not the same thing. You will finish the Raft paper feeling you understand Raft. You will discover in week 61 that you cannot implement §5.4.2. The protocol below is designed to convert recognition into something checkable before you have spent the week.

The Three-Pass Method

Adapted from Keshav's How to Read a Paper, with the modifications this track needs.

Pass 1 — Five minutes. Should I read this at all?

Read: title, abstract, section headings, conclusions, and the references (skimming for names you recognise).

Then answer, in one line each:

CATEGORY  : what kind of paper is this? (new mechanism / evaluation / survey / position)
CONTEXT   : what does it assume I already know?
CLAIM     : what is the one-sentence contribution?
CORRECT   : does the claim seem plausible? what would make it false?
FOR ME    : which milestone does this serve, and could I do that milestone without it?

If "FOR ME" is blank, stop. That is the whole point of pass 1 and it is where the reading budget is protected. A paper with no milestone goes on the parking list.

Pass 1 rejects perhaps a third of what you pick up, at a cost of five minutes each.

Pass 2 — One hour. What does it actually say?

Read the body, skipping proofs and most of the evaluation. Look at every figure and table; a well-made figure carries more than the paragraph describing it.

Produce an extraction note. If you cannot, you have not understood it well enough to use it — which is a valid outcome and means either pass 3 or finding a better source.

Pass 2 is the default for most of this track's readings. Most papers deserve pass 2 and nothing more.

Pass 3 — Two to five hours. Could I reimplement this?

Reserved for papers you are about to build from. In this track that is a small set: Raft, HNSW, LSM-Tree, Dataflow, TPU, the AD survey.

The method: re-derive everything. Read a claim, close the paper, work it out, compare. Where you cannot re-derive, you have found either an unstated assumption or a gap in your understanding, and both are worth marking.

Pass 3 ends when you can sketch the mechanism on a whiteboard from memory and state where it breaks.

Reading After Building, Not Before

The single most important scheduling rule in this track, and it inverts the obvious order.

The rule: for any paper describing a mechanism you are about to build, do pass 1 before, and passes 2 and 3 after your own naive design exists and is committed.

Why. Step 3 of the loop — reconstructing a system from its constraints — is only trainable if you attempt the design before seeing the answer. Once you have read the paper you cannot un-read it, and that week's opportunity is permanently gone. There are only fifteen of them.

What this looks like in practice, from P02:

Three separate readings of two papers, each immediately before or after the milestone it serves. Total: 5.5 hours. The alternative — reading both papers in week 9 — costs the same hours and destroys weeks 10 and 11.

The diff is the deliverable. After reading a paper post-design, write:

1. What did they do that I did not think of?
2. What did I do that they do not — and is mine wrong, or just different?
3. Which of my decisions did they make differently for a reason I can now state?

Question 3 is where the learning concentrates. It is also the raw material for the report's section 3.

The Extraction Note

One per paper, ~200 words, in notebook/reading/<year>-<firstauthor>-<slug>.md. If a paper does not justify 200 words it did not justify an hour.

# <Author year> — <Title>

MILESTONE   : which milestone this serves
PASS        : 1 / 2 / 3
TIME        : actual minutes spent

## The one idea
<one sentence. If you need two, you have not found it yet.>

## The mechanism
<how it works, in your words, 3-5 sentences. No quoting.>

## The number
<the single most important quantitative claim, with its conditions.
 If there is none, say so — it changes how much to trust the paper.>

## What surprised me
<the thing you did not expect. If nothing, you skimmed.>

## What they assume
<the assumption doing the most work, and when it fails.>

## What I distrust
<the evaluation choice you would attack. Every paper has one.>

## For my build
<the specific thing I will do differently because of this.>

## Unresolved
<what I still do not understand. Name it — it is the re-read target.>

"What I distrust" is not cynicism, it is calibration. Every evaluation section makes choices favourable to the authors: the baseline they picked, the workload, the scale, the metric. Naming one per paper builds the reflex that makes you a good reviewer of your own work — which is the skill P15 is finally graded on.

"Unresolved" is the field that compounds. Over 34 months these accumulate into a map of your own gaps, and retention.md turns them into review items.

Reading Code

Roughly a third of this track's reading is source code — LevelDB, xv6, hnswlib, etcd/raft, CPython's ceval.c. Code needs a different protocol, because it has no abstract and no figures.

The five-step method:

1. Find the entry point and the data structure. Not the algorithm — the shape of the state. In LevelDB that is Version and MemTable; in xv6 it is struct proc. A system is its data structures; the functions are how they change.
2. Read the header/interface first, whole. It is the author's own summary of what matters, and it is short.
3. Trace one operation end to end. One Put. One fork. One search. Follow it through every layer, writing the call chain by hand. Do not branch out.
4. Find the thing you would have got wrong. There is always one — an ordering constraint, a lock discipline, an error path. It is usually commented, and the comment usually explains a bug.
5. Then read broadly.

Time-box it to two hours and stop at the boundary. Codebases are unbounded; papers at least end.

Read after your own implementation, for the same reason as papers. Reading LevelDB's version_set.cc after building compaction is an education; before, it is copying.

When To Stop

Reading has no natural terminator, so it needs an artificial one. Four:

The most important stopping rule is the fourth, because it is the one that feels worst. The reference in section 4 will be genuinely interesting. Following it is how a 1-hour budget becomes an evening, and how a track becomes a reading list.

The 15% cap is a cap, not a target. A week with 20 minutes of reading and a working mechanism beat a week with 4 hours of reading and a broken one, every time.

Worked Example — Raft §5.4.2

The hardest paragraph in the hardest paper in the track, and the one whose absence causes a bug appearing in ~1 run in 10⁵ that destroys linearizability.

Pass 1 (week 55, 5 min). Category: new mechanism. Claim: consensus can be made understandable by decomposing into election / log replication / safety, with a strong leader. For me: P05 milestones 6–8. Read it.

Pass 2 (weeks 57–58, 3 h, split). §5.1–5.3 before milestone 4, the rest before milestone 6. Extraction note produced. "Unresolved: why can't a leader commit an old entry by counting replicas? The paper says so; I do not see the failure."

Pass 3 (week 61, 2 h). The unresolved item is now the milestone.

The method for one hard paragraph:

1. State the rule. A leader may not commit an entry from a previous term by counting replicas; it must first commit an entry from its own term.
2. Assume the rule is absent. What could go wrong?
3. Construct the counterexample by hand, on paper, as a space-time diagram. Five nodes, terms, logs. This is Figure 8 in the paper — cover it and build your own first.
4. Compare against theirs. If they differ, one of you is wrong and finding out which is the entire value of the exercise.
5. Write the test. A test that constructs the interleaving deliberately, because it will not arise by chance in a thousand runs.

Budget: 2 hours for one paragraph. That is the correct allocation. §5.4.2 is worth more than the rest of the paper combined for an implementer, and reading it at uniform speed with §2 is how the bug ships.

Worked Example — Reading LevelDB

Scheduled after P04 milestone 9 (size-tiered compaction working). Two hours.

Step 1 — the state. db/version_set.h. Version is an immutable list of files per level; VersionSet holds the current one plus a list of live older ones. Stop and notice: versions are immutable and reference-counted. That is the concurrency design in one observation — readers pin a version, compaction produces a new one, nobody locks.

Step 2 — the interface. include/leveldb/db.h, ~200 lines, whole. Note what is absent: no transactions, no secondary indexes, no iterators over multiple DBs. The scope boundary is the design.

Step 3 — trace one Put. DBImpl::Put → Write → WriteBatch → the WAL append → MemTable::Add → maybe MakeRoomForWrite. Write that chain out by hand.

Step 4 — the thing you would have got wrong. In MakeRoomForWrite: a deliberate 1-millisecond sleep when L0 has too many files. A sleep, in a database write path. The comment explains it as a throttle to smooth latency rather than let it collapse later — this is the write stall, and seeing it in production code lands harder than reading about it.

Step 5 — broaden, if time remains. version_set.cc's compaction picker.

Extraction note focuses on step 4, because that is what your own implementation is missing.

The Anti-Patterns

Budget Discipline

~183 hours over 130 weeks ≈ 1.4 h/week, and it is deliberately front-loaded onto milestones rather than spread evenly. Some weeks are 3 hours; many are zero.

Per project, from readings.md: P05 has the largest budget at 20 hours, P04 at 15, P12 at 17. Those three account for 28% of all reading and it is correctly allocated — they are the projects where getting the concept wrong costs the most weeks.

Track it. In the weekly log:

READING : Raft ss5.4.2 (pass 3) — for milestone 7 — 2.0 h [budget 2.0]

If actual exceeds budget by more than 50% for two consecutive weeks, you have drifted into consumption mode. The remedy is mechanical, not motivational: cap the next two weeks at 30 minutes and see whether the milestones still complete. They will, and that is the lesson.

References

• Keshav, S. How to Read a Paper. ACM SIGCOMM CCR 37(3), 2007. Three pages; the source of the three-pass structure. Read it first — it costs ten minutes.
• Roediger, H. L., Karpicke, J. D. Test-Enhanced Learning. Psychological Science 17(3), 2006. Retrieval beats re-reading; the empirical basis for "close the paper and reconstruct".
• Karpicke, J. D., Blunt, J. R. Retrieval Practice Produces More Learning than Elaborative Studying with Concept Mapping. Science 331(6018), 2011.
• Dunlosky, J. et al. Improving Students' Learning With Effective Learning Techniques. Psychological Science in the Public Interest 14(1), 2013. Ranks ten techniques by measured effectiveness. Highlighting and re-reading score low utility; practice testing and distributed practice score high.
• Adler, M. J., Van Doren, C. How to Read a Book. Simon & Schuster, 1972. The inspectional/analytical/syntopical distinction that the three passes descend from.
• Peyton Jones, S. How to Write a Great Research Paper. Microsoft Research, 2004. Read from the other side: knowing how papers are constructed tells you where the authors put the contribution and where they hid the weakness.
• Feynman, R. P. Cargo Cult Science. Caltech, 1974. Why "What I distrust" is a required field.