I begin by asking some questions about the subject of the tutorial. Foremost, a tutorial teaches the reader how to accomplish something. FIRST -- What is that "something?". As a skilled observer, the tutorial author might be expected to know about the finished product of the student's efforts. SECOND -- How might the student see/know that they have created correct results? Is there one correct way to create the end results or are there multiple variants that deliver alternative results that are "good enough." ALSO -- How might the student see/know that they have undesired results. Are these results not correct and useless or are they useful but somehow not desirable? [This is a major concern.]
Using the answers to these questions, I then fashion at least one, but preferably two or three example cases that walk through from start to finish. These cases all have the target accomplishment in sight. The first such case has a dual purpose. First, it shows the student that they have a working environment. Armed with such an environment, the student can then see that they, too, can create useful results even thought they might have little understanding of the hows and whys. The next cases get progressively more complex and challenge the student. I withhold most discussion of theory or technical detail for delivery in these later cases. Often, I omit those details entirely and direct the student to another document if they want to delve into the gritty details.
I begin by asking some questions about the subject of the tutorial. Foremost, a tutorial teaches the reader how to accomplish something. FIRST -- What is that "something?". As a skilled observer, the tutorial author might be expected to know about the finished product of the student's efforts. SECOND -- How might the student see/know that they have created correct results? Is there one correct way to create the end results or are there multiple variants that deliver alternative results that are "good enough." ALSO -- How might the student see/know that they have undesired results. Are these results not correct and useless or are they useful but somehow not desirable? [This is a major concern.]
Using the answers to these questions, I then fashion at least one, but preferably two or three example cases that walk through from start to finish. These cases all have the target accomplishment in sight. The first such case has a dual purpose. First, it shows the student that they have a working environment. Armed with such an environment, the student can then see that they, too, can create useful results even thought they might have little understanding of the hows and whys. The next cases get progressively more complex and challenge the student. I withhold most discussion of theory or technical detail for delivery in these later cases. Often, I omit those details entirely and direct the student to another document if they want to delve into the gritty details.