Post History

Source: https://writers.stackexchange.com/a/37742
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

In addition to [grouping steps that must be done together](https://writing.stackexchange.com/a/37730/1993) and [teaching troubleshooting](https://writing.stackexchange.com/a/37732/1993), 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.

Original score: 13