Seth's Blog : Two kinds of instructions

Two kinds of instructions

The more common, easier to execute sort: Instructions to remind people who already know what to do, what to do.

The more essential and harder to create kind: Instructions for people who don’t know what to do.

It’s a mistake to assume that just because you know all the steps, the person you’re writing for does as well.

[Almost all instructions on car dashboards, and most on the highway, are for people who already know how to drive and where they’re going… instructions that teach are a special category.]

Here are some steps to consider:

Decide in advance what sort of instructions you’re creating.
Put a value on getting it right. You probably don’t need to sweat the instructions that come with a yo-yo, but maybe improving the manual for that CNC router is the best way to grow your brand’s reputation.
If it’s for a new user, make sure that someone like that is on the team, or even better, put that person in charge.
Start with big picture concepts and an overview before getting to step 1.
Earn enrollment in a patient journey and treat the learner with respect.
When in doubt, take advantage of links, videos and other methods to give frustrated users a chance to dig deeper (it’s hard to do this with street signs and other real world interactions, but if you’re connected to the net, it’s always a good idea). Every interaction should have a, “what if the person is confused in this moment?” branch.
Get feedback from users and update the instructions regularly. Shipped is not done. Shipped is the beginning.
Consider asking Claude to review your instructions with a beginner’s mind and to restate what is being described. If it doesn’t translate, it’s probably not clear.

This is more challenging than it looks. That’s okay. That’s why we need you to do it.