A precondition stated after the instructions that require it is read too late to help

The lesson

Instructions and their preconditions are usually written as two separate thoughts — "here's how to do it" and, somewhere else, "by the way, you need X first" — and the natural drafting order puts the how-to first because it's the reason the page exists. But a reader consumes the page top to bottom and acts as they go: the first copy-pasteable command is often copied before the rest of the page is read. If the precondition that makes that command work is stated later, the reader has already acted on incomplete information by the time they'd see it.

This is easy to miss during writing because the author already holds the precondition in mind — it doesn't feel like withheld information, it feels like context that will "come up." It only becomes a problem for someone encountering the page cold, which is exactly the audience a getting-started page is for.

The fix is purely about position, not content: whatever fact would explain why the primary instructions might fail belongs before those instructions, ideally as the first thing on the page — not because it's the most important fact overall, but because it's the one piece of context every subsequent instruction depends on.

The failure that taught it

A getting-started page offered two paths to install a tool: paste a prompt to a coding agent, or run a short sequence of terminal commands, both starting with cloning a repository. Near the bottom of the same page, a separate section explained that the repository was private and access had to be requested first. Anyone following the page in order would hit a clone command that fails before ever reaching the sentence that explains why — the explanation existed, but its position made it functionally unreachable for the reader who needed it most.

How to apply it

When writing or reviewing a setup/onboarding page, identify anything that gates the primary instructions — access, a required tool version, an environment variable, a paid tier — and check its position relative to those instructions, not just its presence. If a precondition is stated after the steps that depend on it, move it to the top, even if that feels like leading with a caveat instead of the value. Read the page in the order a new user would act on it, not the order that felt natural to write it in: the test is whether the first thing a reader could copy and run would actually work given only what they've read so far.