I just co-wrote a very detailed tutorial about how to use GitHub and the Terminal, which assumes no prior knowledge of either GitHub or the Terminal. (It also includes animated gifs.)
While writing the guide, I realized that really good tutorials should have at least three people working on them:
Person 1 has just learned the task and is writing up how to do the task immediately after learning it. This person knows what s/he didn’t know before learning the task, and explicitly writes how to do each of those steps.
Person 2 is skilled or experience in the task, and is able to fill in the holes that Person 1 has. (In my case, Person 2 also taught me these skills. This was an added bonus
The document is initially written by Person 1, with insight and additional information from Person 2.
I’m going to test this theory out again with a future tutorial, but I think it worked out really well for this one. Please let me know how you construct tutorials (written, audio, video) or any thoughts you have with the hashtag #sandboxtutorial on Twitter. (Or email me.)
Have a great day! Mel
www.tinyletter.com/melodykramer
Update Jesse writes “Might I also suggest “person tester” someone who would benefit from the tutorial and with fresh eyes tries to follow the steps to complete the tutorial. Observe them using it and make revisions as necessary.”
Ivan writes, “A (“A” as in “my”) way of doing tutorials (for lack of better resources, namely people) is to do one draft public and basically seek input, along the lines of “this is what I did to make this work, but if you have a better way, share, pretty please. I like the idea having others look at things but in tutorial-land sometimes you’re it, especially if you’re trying a hack (for a small pub, to boot), even though it always helps to google things. Love the gifs.”
I should have pointed out that we did both of these things. You can see how the post was revised (with lots of input) here