Context before action

Ordering concepts appropriately in instructions so the reader can follow

This is called "Action Before Result" or "Context Before Action" and prevents "instructional blindness" (when a reader starts an action before they realize they are in the wrong place or don't have the right tools). In UX writing this is called "front-loading."

Details should be mapped based on how the user will perform them. Include prereqs first, and make no assumptions.

• Enter the platform, then do the action.
• Don't assume they're already in the platform or know to go there first, even if the guide is about that platform (especially if the guidance includes other platform work)
• If there are many prereqs, include them as a section before the instructions - ensure the reader has the right platform, permissions, and tools before they even begin

Place the goal/context first, then the details after that.

• (bad) Do this to do that.
• (good) To do that, do this.

You should tell the reader where an action should take place (or the conditions, objectives) before describing the action to take - where before what, who before what, etc.

• "Click submit if you are an admin" vs "if you are an admin, click submit"
• In the first scenario, the non-admin user may have already clicked submit before realizing it doesn't apply to them.

Links/references

• [1]
• [2]
• [3]
• [4]