A number from September changed how I write a how-to: on the estate's docs sites, pages at search positions four to ten were clicked 0.31% of the time. Three clicks in a thousand appearances.
Something is reading those pages, though. Assistants fetch a page when somebody asks a question, answer, and move on. The person who asked never sees the page.
The pages fetched most weren't the best-written or the most complete but the ones whose first screen was a quotable command. Open with preamble and the assistant quotes the preamble.
So the rule is now:
• A how-to opens with the thing that does the job: the command, config block or API call, ten lines at most, plus one sentence saying what it does.
• A reference page opens with whatever a person came to look up.
• Everything the page used to say first goes underneath.
afmpeg's remux guide went from 132 words before the first line of code to 27. The paragraph about stream copies is still there, word for word, directly underneath.
You can check it from the shell: count the words between the title and the first code block or table. Under a hundred is answer-first. It's a number you can put in a merge request, and it takes the argument out of review.
One exception: tutorials. Their reader has chosen to sit down and learn, and the walk is the thing they came for.