28

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?

  • Are there at least any linters, source-code checks, static checkers or unit tests/ doctests you can use to catch the most common basic mistakes/ syntax errors? When facing this sort of situation I just brew something up with grep/PERL/Python etc. – smci Jul 19 '18 at 0:15
  • This question reminds me of what the Apollo 13 crew had to go through when powering up the command module for re-entry. To save power, they left the instrumentation system off until the end, so they performed the entire power-up procedure in the blind. If they made any mistakes, it wouldn't have been detected until the end, by which point it would've been too late to fix. – ahiijny Jul 19 '18 at 2:10
  • one thing i wonder is if there's really no feedback at all? error messages can still be valid feedback. If after the first step, attempts to run the code yield a "module Step2Module not found" error on success, and a "syntax error" on failure, that feedback is worthwhile, if unconventional – dn3s Jul 20 '18 at 5:30
32

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.

13

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.

  • 3
    +1 for troubleshooting. If you've got multiple steps, you've got multiple ways the user can screw up, or the system itself can be faulty. The validation stage for those steps needs to cover ways all those steps could go wrong so that you can fix the missing step. – Graham Jul 19 '18 at 7:56
11

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.

5

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.

  • How does the user know if they're moving forward or backward? A change may fix the problem to produce a new error, or introduce a bug which also produces a new error. This is a massive problem developers face and one that can be very frustrating. Getting a new error message each time is not a reliable sign of progress. – user28281 Jul 18 '18 at 16:43
  • 1) For exactly this example (implementing a new complete functionality in RoR), this works very well in practice if you're so inclined. Obviously if you're practiced you can implement all of half a dozen steps right from the get-go, but if you're out of practice a bit, you can fall back to this mode. 2) More importantly, that is what the OP asked: how to show progress although the reader of his tutorial is not yet finished. If the error messages are not obvious, he can list them in his tutorial. – AnoE Jul 18 '18 at 19:07
4

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.

  • I don't see anywhere that the OP is talking about modifying code. A "technical tutorial" could just as easily be one on how to physically hook up a network, or make a change to their car. Can you Edit this to clarify how it answers the question as asked? – a CVn Jul 19 '18 at 8:22
  • 3
    @MichaelKjörling The OP says, "Sometimes the tutorials require adding and modifying code in multiple files, before any effect can be previewed." – Craig Sefton Jul 19 '18 at 11:51
  • 2
    I wrote it to OP's specific task at hand, but I think the principle of my answer applies with 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. Come to think of it, lack of this kind of material is a big peeve of mine with the Haynes manuals (technical writing for automotive repair). – R.. Jul 19 '18 at 15:00
  • 1
    @R.. "lack of this kind of material is a big peeve of mine with the Haynes manuals" Especially in that case, you might want to edit it into your answer. :) – a CVn Jul 19 '18 at 16:39
  • 2
    @MichaelKjörling: Done. Thanks for the suggestions. – R.. Jul 19 '18 at 18:20

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy