Follow the on-screen instructions

Earlier today, the following question was asked in a community of which I am a member:

Do you ever write "Follow the on-screen instructions?"

This question came at an apt time for me, since I have been using this phrase and variants more over the last few weeks.

I use the phrase "Follow the on-screen instructions" when there is a detailed product wizard that will guide a user through everything they need to complete a task. This is a prerequisite. If the product does not clearly explain every step a user needs to complete a task, I will not refer them to the product. Instead, I will provide a detailed description of steps the user needs to take in my documentation.

Consider this usage of the phrase "Follow the on-screen instructions" from a recent post I wrote:

Follow the on-screen instructions to configure your model training job. We recommend using Fast training and training from the MS COCO checkpoint. When your training job starts, an estimate will appear that shows how long we think your training job will take to complete.

This paragraph is from an article that explains how to detect brand logos in videos. My goal for this post was to equip the reader with all the knowledge and code they need to detect brand logos in videos. Part of the guide involves training a computer vision model. We have an interactive wizard in our product for this process since there are a few areas to configure. I could have explained every step of the wizard in my post, but I would be providing little value beyond what is already in the product.

Indeed, there is a risk when you document wizards that the process may change. A new page may be introduced to the wizard which will affect the flow of your written instructions. Fields could be renamed. Order could be changed. In all cases, such changes to the wizard will affect the coherence and usefulness of your written explanation. By referring the user to the wizard, I know that they will get the most up to date information on how to complete the intermediary step -- training a model -- on their way to achieving their goal.

With that said, you should provide the requisite guidance to complete a flow. In the example above, the wizard to which I point a user has three screens. The screens walk through:

1. Choosing training speed (Fast, Accurate)
2. Choosing a model checkpoint
3. An announcement that the training job has started

I mention in my article that a user should use Fast training from the MS COCO checkpoint. (NB: "MS COCO checkpoint" is a term in our product, so the use of this jargon is appropriate in the guide.). This is because the point -- using Fast training and the MS Checkpoint -- is essential for the reader to understand. Choosing another checkpoint is a path taken by advanced users.

I could provide more detailed instructions, but doing so feels redundant; the product serves is here to help.

Where a user needs to do something that is non-standard (i.e. an action that is hidden by a menu in a wizard), you should call out tand explain the action explicitly in your tutorial. This ensures the reader knows that they shouldn't click "Continue" or whatever button you have in your wizard to proceed to the next step without first changing a setting or toggling an option.

In my article, I also note the end condition:

When your training job starts, an estimate will appear that shows how long we think your training job will take to complete.

This sets clear expectations for the reader in terms of what should happen when they complete the wizard. With this text, I can reassure a reader that their seeing training job estimate information is indicative that their training job has started. Reaching this goal marks completion of another step in my guide.

Summary

To summarize, "Follow the on-screen instructions" is an appropriate term to use in documentation when you have a complex set of instructions that are clearly explained by a wizard. This term allows you to guide a user to accomplishing their goal without explaining steps one by one that are already documented clearly in the product. But, you should always provide best practices to ensure a user is going in the right direction. Where a user needs to do something non-standard, explicitly state the required action in your content.