4

The Angular Tutorial shows the technique in action. The experience for the tutorial follower is:

  1. First, clone the repository.
  2. Next, check out step 1 to get the repo into the appropriate state.
  3. Then follow the instructions for step 1 in the tutorial.
  4. Next, check out step 2.
  5. Follow the instruction for step 2.
  6. Continue.

The terminal commands to begin the Angular Tutorial are:

git clone git://github.com/angular/angular-phonecat.git
cd angular-phonecat
git checkout -f step-0

What's great about this is that you skip straight to any step you want and start from there.

How does one go about designing this type of tutorial experience? What are some best practices for this method? Is it possible to go back and edit a particular step without affecting others that come before or after it?

Chris Calo
  • 7,518
  • 7
  • 48
  • 64
  • While programming related, not sure if this falls under the domain of SO. – Woot4Moo Jan 07 '13 at 17:23
  • Related questions: [Version control setup for a tutorial](http://stackoverflow.com/questions/5924302/version-control-setup-for-a-tutorial), [Tagging steps for a tutorial?](http://stackoverflow.com/questions/24928115/tagging-steps-for-a-tutorial) and [Using git commits as tutorial/workshop steps?](http://stackoverflow.com/questions/28516302/using-git-commits-as-tutorial-workshop-steps) – xverges Mar 17 '15 at 20:15

1 Answers1

1

i would say to start by thinking about each step in your tutorial. then doing the development for one step and commit it. then write that section of the tutorial. then move on to the next section, code it, commit it, write it, REPEAT!

as far as going back w/o effecting others, you will not intrinsically be able to commit from a detached head in your repo. you'd have to branch out from that previous position. but honestly that might be better for users.

this is actually a pretty cool idea. but i would think that non-git users would need a primer tutorial about moving between commits (checkout)

xero
  • 4,077
  • 22
  • 39
  • Don't you have to tag each step? – Chris Calo Jan 08 '13 at 23:47
  • tags are always optional. they create pointers that are easier to users to type/remember. e.g. `git checkout e08847ae7a` vs `git checkout tagName` -- but for this tutorial setup tags would probably be better. just add the tag right after your commit. i was wondering what the step-0 thing was in your first post. now i realize it's a tag name. – xero Jan 09 '13 at 16:06