Imagine the setting: me, sitting at a computer, making an appointment with a pharmacy.

Riveting, isn’t it?

It should have been a short interaction, but I had needed an answer first.

The appointment was for a COVID booster… could I get my flu shot at the same time? The FAQs had my question… and a video answer from a pharmacist (or an actor playing a pharmacist).

The video started with why vaccines are important and safe. After 30 seconds or so, I wondered whether I’d selected the right video. Here’s the script I wish they’d used:

To their credit, the text FAQ has exactly what I want:

Their video did the animated version of a recipe blog post. It’s all life story and preamble (usually to beef up the word count for SEO) and you’re scrolling for the one thing you want: the recipe!

You would be right to notice that this email may feel like it’s searching for the point, so here it is: different content has different needs.

References should be focused on factual answers. Your other docs provide context around why devs would use your product. The type of content that will attract the right developers has a completely different job.

Too often, teams publish content that is technical, without knowing what it needs to accomplish.

The “jump to recipe” pattern is a sign of content that is misaligned with what the audience wants. Technical content has similar anti-patterns.

You can prevent these mistakes in the first place when you use EveryDeveloper’s proven system (in convenient checklist form).

And the next time you experience a rambling introduction or find yourself spelunking for the recipe… remember that all content—including your own—needs to help the reader accomplish their goals.