search

codebar / tutorials

🗒 codebar's tutorials
http://tutorials.codebar.io/
260 stars 242 forks source link

REST for beginners tutorial #102

Open despo opened 10 years ago

phil commented 10 years ago

Hi @despo I didn't get the chance to say hello at brighton ruby, but i'd like to help out the codebar team with a few of these outstanding issues. Do you have any templates to start me off, or can i just jump in with a pull-request?

jkbits1 commented 10 years ago

Hi @phil When I started working on the sql tutorial a few days ago, I found it helpful to make a copy of the first Javascript tutorial, and make changes to that. It's not a perfect approach, or one that suits everybody, but it has helped me with the general tone and pacing of the tutorial.

My ongoing draft work is here, so you can judge for yourself whether this approach is useful: https://github.com/jkbits1/tutorials/tree/sql-tut-drafts/sql/lesson1

despo commented 10 years ago

@phil Hi Phil, sorry for not getting back earlier. Thanks for offering to help out. There is no template, but if you have a look at the existing tutorials, I think its easy to get the idea as Jon mentioned above.

A brief guide.

  1. Preparing exercises. Something interesting; a small game or app that the student would be keen to show around or would be able to use. Building and adding them under /examples so there is a live demo of the end goal. (this is something we can collaborate on and/or discuss with others on the mailing list or the gitter channel)
  2. Briefly introducing the topic, too much detail is unnecessary as these are guided tutorials and there is a coach around to help as well
  3. Explaining and getting the students to focus on one new thing at a time instead of presenting them with a lot of content and usage examples and then a long exercise.
  4. Repetition is good. A tutorial can contain multiple exercises that ask the students to take similar steps (e.g. for HTTP Requests one exercise introduces GET, another has GET and POST etc)
  5. Adding bonus. Bonus should not be necessary for understanding the tutorial. Ideally something taught in one of the previous tutorials, to get them to practise something they already know and also give them some encouragement - as new things are always harder to work on.
  6. Linking useful resources (e.g. https://rested.io/ for running requests)
  7. Preparing files. For example, in most of the javascript tutorials we provide HTML and CSS ready to plug in as its easy to get caught up in the little details and not focus on what the tutorial is trying to teach.

I think this is roughly it but if you need any help or more guidance maybe we can have an open discussion at https://gitter.im/codebar/offtopic-discussions

@jkbits1 I hope this is helpful for you too.

jkbits1 commented 10 years ago

@despo Hi Despo, this is a really excellent guide, thanks for posting it.

I don't know if we have a place for things like this, but it would be very handy to keep this advice somewhere.

I'll definitely consider these points for the sql tutorial.

despo commented 10 years ago

@jkbits1 thanks, made a couple of small edits as well.

Yes thats a good idea, will add a contributing page.

phil commented 10 years ago

thanks @despo, thats helped a lot in trying to figure out what would be relevant for teaching purposes. I might hopefully have something ready for a pull-request soon

despo commented 10 years ago

@phil awesome. Help wanted label is now off. If you need anything do not hesitate to get in contact through email/twitter/gitub etc.