Instruction

In addition to concept and specification, a clean piece of documentation will instruct a user in how to accomplish common tasks. These are commonly termed walkthroughs, tutorials, how-tos, or recipes. 

Primarily, a user, regardless of whether they are a programmer or end user, is concerned with how to get from where they are to where they want to be. They are interested in knowing what steps to take. Without instructions for common use cases, they'll be left desperately piecing together what they know about your software from intuitions or other pieces of documentation. Consider a book about cookery that only details the ingredients and their behaviors when cooked, but doesn't contain any specific recipes that combine ingredients in a specific order. That'd be a challenging cooking book to make use of. While it may provide a highly detailed set of culinary information, it doesn't help users answer their actual questions:

When composing instructions, whether they're in the form or video tutorials or written walk-throughs, it is important to consider what use cases are most prevalent or challenging for your users. As with many things in life, you can only reasonably cater for the bulk of prospects, not all of them. It is unreasonable to create tutorials for every single possible use case. And likewise, it is unreasonable, from a user's perspective, for you to only provide a singular tutorial for the most common use case. It is wise to strike a compromise and have a small collection of tutorials that each express:

  • Upfront expectations and prerequisites: A set of instructions should specify what expectations the author has about the reader's hardware, software environment, and capabilities. It should also say if there is anything the reader should prepare before beginning the following steps.
  • Specific steps that a reader can emulate: Instructions should have a number of specific steps that users can follow to reach their desired goal. The user should not have to use too much (or any) initiative when following these steps; the steps should clearly and exhaustively outline exactly what the user needs to do, with code examples if possible. It should also be obvious to the user that they have successfully completed each step (for example, you should now receive X output).
  • An achievable and observable goal: Instructions should work toward a goal that can be observed by the user. It would be upsetting for the last step of a tutorial to say this won't currently work, due to X or Y, but you would usually expect to see Z. Ensure that your software is operating in such a way that the tutorial can be completed to its very end and the user can come away having gotten closer to whatever their overarching goal is.
Don't just tell a user what to do. Tell them what they're accomplishing at each stage, and why it matters. That is, don't just tell me to put salt in the dish, tell me why it needs salt!

The instructional part of documentation is probably the most challenging. It requires us to take on the role of teacher and see things from another person's position of relative ignorance. Maintaining focus on the person we're teaching, the user, is absolutely vital. This feeds quite nicely into our final aspect of clean documentation: usability.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.22.51.241