Examples, Diagrams, and Small Models

By the end of this lesson, you will be able to...

• Choose an example, trace, diagram, or small model for the relationship a reader needs to inspect.

• Explain one mechanism through a compact representation with visible intermediate states.

• State what the representation leaves out before a reader mistakes it for the full system.

Idea in one sentence: Pick the smallest representation that makes the important change visible, then name the simplification that could mislead the reader.

Core Insight

The import-worker queue grew because workers retried database writes. Lesson 005 made that claim concrete. A new reader still asks a harder question: how can a retry make a backlog grow when each job is supposed to finish quickly?

One paragraph can state the answer. It often cannot show it.

The writer might add a decorative architecture diagram, an unrelated code sample, or ten log lines. Those add material without exposing the relationship the reader needs: a failed write returns to the queue, several workers repeat that action, and the queue receives work faster than it drains.

An example, diagram, trace, or small model is useful when it makes one hidden relationship inspectable. It is not a reward placed after the real explanation. It is part of the explanation.

Start With the Relationship, Not the Format

The naive question is:

  Should this lesson use an example, a diagram, or a model?

That starts with the writer's format. Start instead with the reader's missing view:

  What must the reader see change, compare, count, or decide?

For the import incident, the reader needs to see a loop and its consequence. They do not need a full deployment topology.

Plain meaning:

Choose the representation for the question, not for variety.

In the import situation:

The pressure is repeated work arriving faster than workers can finish it. A short event trace exposes that loop better than a box-and-arrow diagram of every service.

Technical name:

This is a representational choice: selecting a simplified view that preserves the relationship needed for one reader decision.

A Worked Retry Trace

Assume one import job takes one database write. The database has no free connection for a moment. The worker's first response is to retry.

Now add three workers following the same rule. They do not create new customer files, but they create more attempts. The queue gains returning work while completed work slows.

  job enters queue
  -> worker takes job
  -> database write fails
  -> worker retries by returning job
  -> queue contains the job again
  -> repeated attempts compete with new jobs

The trace has an input, intermediate states, and a consequence. It also reveals the naive failure: “retry quickly” is reasonable for one job, but repeated retries can increase pressure when the shared dependency is already full.

So far, the table is not a production model. It has done one job: make the feedback loop visible.

Check: A reader must understand why a configuration change is rejected when two fields are set together. Which representation is the strongest first choice?

Think first, then reveal.

Answer: A small valid/invalid comparison table. The reader needs to compare combinations and outcomes. A timeline would show order, which is not the key relationship.

Add a Boundary Note

Every useful representation leaves something out. The omission is not a flaw when the writer names it.

For the retry trace, write this boundary note:

This trace shows one retry rule and one shared database pool. It does not show backoff delays, retry limits, job priorities, multiple queues, or database recovery. Those details can change the size and duration of the backlog, but not the basic loop shown here.

The boundary protects the reader from two mistakes:

1. Treating a toy example as a complete production prediction.
2. Treating the omitted details as unimportant in every system.

A boundary note should name the most dangerous simplification, not apologize for every detail missing from the universe.

Make the Reader Predict

An example becomes a learning tool when the reader can change one condition before seeing the answer.

Suppose import-worker waits 30 seconds before returning a failed job instead of retrying immediately. Predict first:

• What happens to the number of immediate database write attempts?
• What happens to how quickly one job finishes after the database recovers?
• What important risk remains?

The likely result is fewer immediate attempts against the full pool, but a longer delay for any one job. The risk remains that retries can still accumulate if the dependency stays unavailable or if the system accepts new work without a bound.

The model did not tell us the exact production value of 30 seconds. It helped us reason about a direction of change and a trade-off.

Check: A diagram shows an API request, service, and database. It omits a cache that sometimes returns stale data. What should the writer do?

Think first, then reveal.

Answer: Keep the diagram if its purpose is the request's write path, but add a boundary note that the diagram omits cache reads and stale responses. Add the cache to the main diagram only if it changes the relationship the reader is trying to understand.

Trade-offs and Limits

Small representations reduce cognitive load and make a mechanism easier to inspect. The trade-off is simplicity versus fidelity: a smaller model can hide a condition that matters in a real case.

Use a representation when it helps the reader make a specific prediction, comparison, or decision. Do not add it merely because a page looks better with a diagram. A misleading diagram is worse than no diagram because it gives the reader a confident but false model.

You can see the boundary when readers ask a question the representation cannot answer. Link to a fuller trace, reference, or operational document instead of stretching one small picture until it becomes unreadable.

For the retry trace, the unanswered questions include the configured retry limit, which jobs may be dropped, and how long the database remained full. Those belong in the next evidence or operational artifact.

Common Confusions

Confusion: An example proves the general rule

Why it is tempting:

One successful example makes a mechanism feel settled.

Better model:

An example demonstrates one path. State the conditions it holds and the nearby cases it omits.

Confusion: More components make a diagram more explanatory

Why it is tempting:

Completeness looks rigorous.

Better model:

Show only the components needed for the reader's current question. Extra boxes can hide the relationship the diagram was meant to reveal.

Confusion: A model must predict exact production behavior

Why it is tempting:

Numbers and arrows can look authoritative.

Better model:

Small models often explain direction, mechanism, and boundary. They need more evidence before they can support an exact forecast.

Practice: Choose a Representation for a Cache Explanation

A service returns an old account balance immediately after a customer updates it. The writer needs to explain why this can happen and what the reader should expect.

Choose one primary representation: a request trace, a before-and-after state table, a component diagram, or a small model. Then provide:

• the reader question it answers
• the states, actors, or values the representation shows
• one prediction the reader can make from it
• one boundary note about what it omits
• one link target for a reader who needs exact cache settings

A good answer should:

• choose a trace or state table if the main question is when the old value can appear
• show the update, stale cache entry, read, and reader-visible result
• distinguish a useful explanation from a complete cache implementation guide
• state that eviction, invalidation, replica lag, and cache-control rules may change the behavior
• link a working reader to reference for exact TTLs, headers, or configuration fields
• use the evidence discipline from lesson 005 rather than inventing exact delays

Connections

Lesson 005 selected details that carry evidence. This lesson selects the form that makes those details and their relationship visible. Lesson 007 will use the same discipline to design API and reference material for fast retrieval, valid use, errors, and edge cases.

Resources

• [COURSE] Provide Examples — Google Technical Writing — Focus: add context that lets an example guide a reader toward a correct action.
• [GUIDE] Write Accessible Documentation — Google Developer Documentation Style Guide — Focus: use clear headings, text alternatives, and structured content so a diagram does not become the only path to understanding.
• [COURSE] Sample Code — Google Technical Writing — Focus: make examples runnable, relevant, and explicit about expected results.

Key Takeaways

• Choose an example, trace, diagram, or model from the relationship a reader needs to inspect.
• A worked representation should show input, intermediate states, output, and the failure of a naive response.
• Ask the reader to predict a changed condition so the representation tests transfer rather than recognition.
• A boundary note preserves rigor by naming the simplification that could mislead.
• Link from a small explanatory model to the reference or operational material that answers exact follow-up questions.