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