Context before action

In technical writing, "context before action" or "action before result" are fundamental principles for structuring instructions to match how the human brain processes information. Ordering concepts appropriately in instructions ensures the reader does not take premature/incorrect actions before they fully understand the conditions or consequences. It is not appropriate to assume that all users are fully reading the instructions before taking action.

• Context before action refers to placing conditions, locations, or requirements before the instruction.
• Action before result ensures information is presented in the order the user will experience it.

When a reader starts an action before they realize they're in the wrong place or don't have the right tools, this is called "instructional blindness." In UX writing this is referred to as "front-loading."

Examples

Details should be mapped based on how the user will perform them. Include prerequisites 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 to 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.

Technical communication research shows...

Research into technical communication provides reasons why this ordering is critical:

• Act-first instinct: People tend to act as soon as they see words describing an action. If the context/caution is placed at the end, users often perform the action before they reach that information.

<ref>Dana E. Chisnell, Style Guide for Voting System Documentation, August 2008, National Institute of Standards and Technology (NIST)</ref>

Links

• Microsoft style guide: Writing step-by-step instructions
• Google developer documentation style guide: Procedures
• 16 Rules of Effective UX Writing
• Technical Writing Essentials: Writing Instructions
• Style Guide for Voting System Documentation, Page 84: What is technical communication?

References

‎<references />

---