How to construct a technical tutorial when the user can't verify the results after each step?

Question

In a technical tutorial it is helpful for a user to be able to check their progress often. Veryfing that the steps have produced a result is good because the user:

• has a feeling of progress
• can check for any mistakes they've made

However, I'm working with advanced tutorials aimed at developers who are extending a complex product. Sometimes the tutorials require adding and modifying code in multiple files, before any effect can be previewed.

How can I design a tutorial when it is impossible to check the progress in the meantime?

What methods can I use to ensure 1) that the user stays motivated to finish all steps and 2) to minimize the risk of the user making small mistakes that will be hard to trace at the end?

Answer 1

There is not really much you can do in a situation like this other than to clearly alert the reader to the situation up front. If there is no way to verify the next five actions until you have completed all of them, put a warning in big shiny letters saying:

WARNING: The next five steps must all be completed correctly before you can test the result.

That way the reader know what to expect and is not taken by surprise. Not letting the reader get taken by surprise is 90% of the battle here, and the best way to do that is simply to tell them in advance about anything that may be unusual or out of the ordinary.

One thing you might consider doing to further clarify this it to develop a regular step structure in which each step has a action followed by a verification action.

Step 1:
Action: Push the big red button.
Validation: Check that the little green light is on.

Then when you have multiple actions before a step can be verified, combine them into one step:

Step 2:
Action:
1. Eat
2. Pray
3. Love
Validation: Check soul for bliss.

This establishes a pattern for the reader, giving them correct expectations about when validation is possible.

But still use the warning, because explicit is better than implicit:

Step 2:
Warning: All steps must be completed before bliss can be achieved.
Action:
1. Eat
2. Pray
3. Love
Validation: Check soul for bliss.

Answer 2

In addition to grouping steps that must be done together and teaching troubleshooting, give the user a way to recover -- because sometimes the user isn't going to figure it out and is going to bail on you if there's no path forward.

If your tutorial is broken up into units, provide a correct answer at the end of each one. Depending on how you're packaging your tutorial and what the pieces involved are, that might mean shipping answers or it might mean providing download links. If it's something that can be visually inspected ("your dashboard should now look like this"), include screenshots, which allows readers to compare their work to what you intended.

All that said, to the extent that you can support a path where the project always works and gradually gets more advanced, I've found that to work better. I took this approach in a complex visualization package, starting from a bar chart with default axes and graphemes and building to a set of aligned visualizations with different types of charts and compound graphemes, and because it always did something at each step, my users told me they found it easier to learn from than a previous version of the documentation that did not have that progression.

Answer 3

Your question seems to focus on giving the user motivation and error checking. For these, I suggestion two different approaches:

Tell the user why

If you give the user an explanation of why they are doing something, it can help them understand what they are doing to avoid mistakes. If the explanation is interesting, it also acts as motivation to continue.

For example, if your instructions tell a user to insert code into a few different files, your instructions should also provide an explanation of what the code does. It's an opportunity to engage and interest the reader, and helping them understand it will help them debug a potential error.

(Depending on the context, you might also want to think a bit about your writing style. I've read some tutorials that are very dry; others you can just feel the writers passion oozing in the text, and that passion can be contagious, like getting sucked into a good book. I remember sitting down and reading Why's Pogiant Guide to Ruby in its entirety--and I don't even use Ruby. Good writing can be its own motivation to read something technical.)

Tell the user how to troubleshoot

Since you can't validate each step individually, provide a troubleshooting section after all of the steps are completed for debugging issues. For example, if forgetting to add a line to a configuration file would cause a specific error, list the error and how to fix it.

Answer 4

This is not different from what happens in the real world. You could solve your problem like we do in actual development - by being test driven. I.e., make the test a significant part of your tutorial, and make it a high-level feature test (not a unit test).

This way, the reader can execute the test after each step, and get a different error message each time. For example, in Ruby on Rails:

• Write a test that says "if the user clicks the new link XYZ, then the value ABC is read from the DB and displayed".
• First error message will be "link XYZ not found".
• Reader implements (only) the link, with a "href" pointing to the appropriate (new) controller/action.
• Next error message will be "no route found"
• Reader implements the route in config/routes.rb.
• Next error message will be "controller not found"
• Reader implements an empty controller.
• Next error message will be "action not found in controller"
• Reader implements the action.
• Next error message will be "view template not found"
• Reader implements the view template.
• Next error message will be "value ABC not visible"

... and so on, and so forth.

Obviously, this works best if your language/framework of choice is good for this kind of development, and if you have spent time before setting up the testing environment in the context of your tutorial.

Answer 5

If your audience is modifying code whatsoever, they should be using version control. Either you assume they already know how, or you first walk them through the basics before getting into tasks that require modifying code. Then, when it comes time for them to make N steps of modifications without being able to test, you can show them the expected output of git diff or git status or similar, and that's what they use to verify that they followed each step correctly and that the working tree is in the state you expect them to have it in.

While I came up with and wrote this with OP's specific task in mind, I think the same principle applies with a lot more generality. If you can't give the reader steps where the [technical thing] being modified works in a testable way after each step, you instead should give them ways to observe/measure the results of their actions at each step. This may take the form of descriptions of how a physical object should look from different perspectives, points of measurement to check for consistency, etc. A particular example of technical writing I'm familiar with that does not follow this practice well is the Haynes manuals for automotive repair, and it's often really frustrating not being given any information to tell if you've found/removed the appropriate part.