How do you approach writing instructional content in your documentation? Here are some things I’ve tried throughout my career, listed in order of worst to best:
- One task (set of steps) for each GUI screen (yuck)
- Pro: Easy to tell you are complete, takes very little brainpower to “write to the GUI”
- Con: Really unhelpful to readers; they want to get something done, not see everything you can do on a particular GUI screen
- One task for each button in the GUI (yuck)
- Pro: Easy to tell when you’re complete, everything that can be done is documented in some way
- Con: Still not aligned with user goals; a user likely must reference multiple tasks to achieve their goal
- One tutorial/scenario for each user goal (a thing the user wants to do)
- Pro: Closely aligned with user goals, and therefore probably the most helpful approach
- Con: Very expensive to produce, can be difficult to know what user goals really are, it’s hard to know when you’re complete, and some parts of the product may not be “covered” with instructional content
What is your strategy for writing instructional content?
- Have you tried any of the approaches I listed above?
- Have you done something else? If so, please explain!
- Do you have a mix of these types of content or just one?