Write technical introductions for a reader who lacks your context

Michael Lynch identifies common ways technical posts lose readers: long introductions, unexplained jargon and links that act as compulsory homework. His central recommendation is to establish the intended audience and benefit early, then supply enough context for the article to stand alone. Even a sequel should briefly explain the earlier material it depends on.

Michael Lynch · Oct 7, 2026

Why it matters

Engineers writing tutorials, design explanations or incident reports can use the examples to find assumptions their audience may not share.

More context

Try reviewing one draft from the perspective of a specific teammate. List terms that person would recognize, explain necessary unfamiliar ones inline, and move background that delays the main point. Also inspect the rendered article on a phone rather than checking only the source text.

Keep in mind

This is editorial advice with illustrative examples, not an experiment proving one writing style always works. Different audiences need different levels of background; concision should not remove the context needed to understand a technical claim.

Original read