4 ms·

> One problem with this, though, is that I'm still just telling my readers what to do. I would advise you to not write tutorials based in questions. But I've r

> One problem with this, though, is that I'm still just telling my readers what to do. I would advise you to not write tutorials based in questions. But I've read on the diagonal your JS debugging tutorial, and it seems quite "dry" because you are really telling the users to "do this, do that, etc.". I'm a CS teacher, and my approach for my lab classes is to write what I call "guided tutorials", i.e., I guide my students to the answers (as a sequence of steps) but I do not give them the answers. It is a kind of middle thing between something based on questions and a step-by-step tutorial, and it works very well for me. I can send you an example that I gave to one of my classes on network sockets, if you want to check it out (in portuguese though). My email is in my profile.

kaycebasques 9y ago
> my approach for my lab classes is to write what I call "guided tutorials" I think I'm familiar with the approach. One of my favorites is The Elements Of Computing Systems (nand2tetris.org) which gives you the foundational knowledge you need for each chapter, and a spec on what you need to build, and gives you freedom to create it as you see fit. Presumably, though, since you work in lab classes, you also have the "luxury" of being able to talk to your students, and detect if they're stuck... just by watching them. With docs, I don't have that. When it comes to my docs, my current stance is that it's worse to create something that's too open-ended than too closed / dry. If it's too open-ended, readers may get stuck and leave and learn nothing, whereas if it's too closed / dry, my readers may be bored, but at least they'll learn something, or at least have something that they can use when they really need it. Ultimately it really just boils down to a broken feedback loop. I think open-ended approaches are the best way to learn, but I need to know when and where my readers fail, and I need a channel of communication to be able to get them unstuck. So maybe I just need to build a MOOC community around the open-ended docs.
- jventura 9y ago
  > When it comes to my docs, my current stance is that it's worse to create something that's too open-ended than too closed I agree with you as my own approach is also more towards the step-by-step. And you are right that I also have the luxury of my presence being helpful for when the students get stuck, although I try to make my tutorials so that they do not need much of my help. Also, some students cannot go to my classes as they work, and this approach allows them to do the lab assignments at home without much help from me. Regarding the broken feedback loop, one possible alternative for web-based instruction is something that requires the user to insert solutions somewhere and have feedback on it. There's a SaaS that allows you to do programming assignments and you must submit it and run it in their servers. Perhaps you could explore something like that, although with JS you could run it in the browser directly?

kaycebasques 9y ago

> my approach for my lab classes is to write what I call "guided tutorials" I think I'm familiar with the approach. One of my favorites is The Elements Of Computing Systems (nand2tetris.org) which gives you the foundational knowledge you need for each chapter, and a spec on what you need to build, and gives you freedom to create it as you see fit. Presumably, though, since you work in lab classes, you also have the "luxury" of being able to talk to your students, and detect if they're stuck... just by watching them. With docs, I don't have that. When it comes to my docs, my current stance is that it's worse to create something that's too open-ended than too closed / dry. If it's too open-ended, readers may get stuck and leave and learn nothing, whereas if it's too closed / dry, my readers may be bored, but at least they'll learn something, or at least have something that they can use when they really need it. Ultimately it really just boils down to a broken feedback loop. I think open-ended approaches are the best way to learn, but I need to know when and where my readers fail, and I need a channel of communication to be able to get them unstuck. So maybe I just need to build a MOOC community around the open-ended docs.

jventura 9y ago
> When it comes to my docs, my current stance is that it's worse to create something that's too open-ended than too closed I agree with you as my own approach is also more towards the step-by-step. And you are right that I also have the luxury of my presence being helpful for when the students get stuck, although I try to make my tutorials so that they do not need much of my help. Also, some students cannot go to my classes as they work, and this approach allows them to do the lab assignments at home without much help from me. Regarding the broken feedback loop, one possible alternative for web-based instruction is something that requires the user to insert solutions somewhere and have feedback on it. There's a SaaS that allows you to do programming assignments and you must submit it and run it in their servers. Perhaps you could explore something like that, although with JS you could run it in the browser directly?