Where
- Track / page: all tracks — confirmed in bloom-filters and the Data & storage track (bloom-filters, storage-engines, transactions-isolation)
- Section: lesson openings / first concept introduction
What's wrong
Lessons introduce the core concept in abstract terms and then move almost immediately into the technical machinery (bit arrays, hash functions, LSM-trees, RocksDB, SSTables, B-trees, MVCC, etc.) with no everyday hook first. A reader without the systems background has nothing familiar to map the idea onto before the terminology arrives. This is consistent across lessons, including those tagged "Foundation."
Confirmed examples:
- bloom-filters/lessons/what-is-a-bloom-filter — the "definitely not / probably yes" asymmetry is stated abstractly, then tied straight to LSM-trees and RocksDB.
- Data & storage track (storage-engines, transactions-isolation, bloom-filters) — same pattern: concepts open in engineering terms with no real-world analogy to anchor the intuition.
What it should say
Each lesson (or at least each "Foundation" lesson) should open with one short, concrete analogy that captures the core intuition before the formal mechanism and any system/product names. Keep it to a sentence or two so it frames rather than replaces the technical content.
Example for the Bloom filter asymmetry:
Think of a bouncer with a guest list. If your name isn't on it, they can tell you instantly and with certainty you're not invited. But if they think they spot your name, they still double-check at the door — a "maybe yes" needs verifying, while a "no" is always final.
Source (required for accuracy fixes)
Where
What's wrong
Lessons introduce the core concept in abstract terms and then move almost immediately into the technical machinery (bit arrays, hash functions, LSM-trees, RocksDB, SSTables, B-trees, MVCC, etc.) with no everyday hook first. A reader without the systems background has nothing familiar to map the idea onto before the terminology arrives. This is consistent across lessons, including those tagged "Foundation."
Confirmed examples:
What it should say
Each lesson (or at least each "Foundation" lesson) should open with one short, concrete analogy that captures the core intuition before the formal mechanism and any system/product names. Keep it to a sentence or two so it frames rather than replaces the technical content.
Example for the Bloom filter asymmetry:
Source (required for accuracy fixes)