The four layers of every topic

A diagram without an explanation is decoration. An explanation without a diagram is homework. The loop between them — look, read, wonder, try — is where understanding actually forms. Every page on this site is built around that loop.

TL;DR#

• Visualise first, because the shape of a system is easier to hold than its details.
• Understand second, because the mechanism is what makes the picture true rather than merely pretty.
• Get curious third, because the odd facts are what make the mechanism stick.
• Build last, because a thing you have run is a thing you know.
• Skipping a stage is allowed. Skipping the first two is how people end up memorising diagrams they cannot use.

Mental model#

Learning a city from a map is not the same as living in it, but the map comes first for a reason. You orient yourself, then walk the streets, then notice the strange little alley that turns out to be the shortcut everyone uses, then finally drive it yourself without looking at anything.

The four stages are those four things, in that order, for a piece of software.

Where the analogy breaks#

A city does not change while you are learning it. Android does — every year, in ways that sometimes invalidate what you learned. The fourth stage, building, is also how you find out that the map in your head has a stale street on it.

The big picture#

Deep dive#

Stage 1 — Visualise#

Every topic page opens with an interactive diagram. It is interactive for a specific reason: a mechanism is a process, and a static picture of a process invites you to mistake the boxes for the point. When you can step through the sequence, you notice the ordering, the hand-offs, and where things can go wrong.

What to do with it: step through it once without reading the captions. Then again, reading them. Then look for the step that surprised you.

Stage 2 — Understand#

The prose is where the diagram becomes true. It answers the questions a diagram cannot:

• What problem did this solve? Every mechanism exists because something was worse before.
• What did it replace? The replaced thing explains the shape of the replacement.
• What did it cost? Every design is a trade-off; the cost is usually the interesting part.

The deep dive uses real code and real file paths. You are not expected to memorise them. You are expected to be able to find them.

Stage 3 — Get curious#

The curiosity corner is not decoration. Odd facts are memory hooks: "the phone can ring before it is unlocked because of File-Based Encryption" is easier to remember than a definition of Direct Boot, and it carries the definition with it.

The Curiosity Cabinet at /curiosity/ collects all of them across the site.

Stage 4 — Build#

Some topics have a matching project in the builder track. Some have a lab you can run with adb on a real device. Some have both. The point is not to produce an artefact you will keep; it is to notice the moment when the thing you read about does something on a screen.

How it evolved#

This page format did not come from nowhere. It is a synthesis of two traditions: explorable explanations, which put the interactive first, and technical documentation, which puts the mechanism first. Neither alone is enough for a system as large as Android.

Curiosity corner#

• The best explanations of Android are often talks, not docs: the engineers explaining a change at Google I/O are usually describing the problem it solved, which the docs omit.
• A diagram you can break is better than one you can only look at. That is why the interactive simulations let you provoke failures.

Try it#

$ 
adb shell dumpsys activity activities | head -30

Then find the page on Activity and Task Management. You will recognise the output.

Check yourself#

Sources#