I'm currently working on writing a tutorial on saltstack. As I think through the problems of trying to help someone else build a mental model, I feel like I don't really know enough theory of how that is done. It occurs to me that I've never read a close reading or literary/pedagogical analysis of a tutorial. I am currently drawing most of my inspiration from things that I liked about the django and angularjs tutorials, but I really would like to broaden my horizon.
So I want to know: are there any good tutorials I should also check out? Anyone who has written an analysis of what makes a good tutorial?
I don't know of any good tutorials or tutorial theory. However, someone once showed me a trick that works well when describing something complicated:
Start writing at the end. The end of the text should be the first thing you write.
E.g describe the final setup and then fill in all the missing information that is needed to understand the goal.
This makes what you write much more focused.
Another thing that works well is that the text starts by describing a problem. This makes what follows more interesting.