Hi Michael,
Thanks for the suggestion, but we've been down this path before and abandoned it.
Once upon a time -- way back in Django's past -- we actually did have the tutorial code available as part of the Django repository. The problem was keeping the tutorial code and the tutorial itself in sync. If the two ever diverged (because someone made a change and forgot to update the code) or if there was ever an error in the code, then anyone doing the tutorial would get confused -- and that's the worst possible time to get confused, since it's our opportunity to convince someone how good Django is.
There's also the problem that the tutorial goes through 4 steps, and it would be useful to have the code at the end of each step of the tutorial. Maintaining 4 tutorial codebases is also a time consuming process.
Ultimately, the decision was made that there isn't *that* much code in the tutorial, so it was better to just have the text explanation, and get people to type the code. There's also a certain amount of evidence from education circles that this is a good idea anyway -- forcing someone to actually type the code (and therefore engage with the learning process) has benefits over just cutting and pasting some pre-prepared code.
Yours,
Russ Magee %-)
Once upon a time -- way back in Django's past -- we actually did have the tutorial code available as part of the Django repository. The problem was keeping the tutorial code and the tutorial itself in sync. If the two ever diverged (because someone made a change and forgot to update the code) or if there was ever an error in the code, then anyone doing the tutorial would get confused -- and that's the worst possible time to get confused, since it's our opportunity to convince someone how good Django is.
There's also the problem that the tutorial goes through 4 steps, and it would be useful to have the code at the end of each step of the tutorial. Maintaining 4 tutorial codebases is also a time consuming process.
I'm re-opening an old discussion - https://groups.google.com/d/topic/django-developers/MbLD1BL5xkQ/discussion. Sorry if it all comes out weird, I'm having to do it in Google Groups.
I propose maintaining a repository of the Polls tutorial code, with each branch representing the state of the code at the end of each tutorial.
I realise that there is a danger that people might be tempted simply to checkout the code rather than type it in, following all the useful steps and mis-steps that the tutorial provides, but at the same time it would have other significant advantages that it would be a shame to forego just in order to save people from temptation, especially if they are strongly warned against it.
The advantages:A learner likely won't just follow the steps in the tutorial, but will also want to play and experiment, and break things. It will make for a better learning experience if that's possible with the safety-net of being able to return to a known good state.In particular, it will make it easier for the learner to reset their tutorial code so that they can go on to the next tutorial after playing freely with it. And sometimes, it might be weeks or months later that they want to do part five, or go back to have a look at some particular thing in it from an earlier stage.
It will help the documentation writers. It's difficult to build on the work in the tutorial if it's not easy to get where it was. For example, a new tutorial could use the Polls application to tackle logging or static files - which is what I would like to start doing now - but it's quite a bore to have to go through all the steps in all the previous tutorials just so you can start writing it.
I think it would be worthwhile having an official repository for this purpose.
Hi Daniele,On Thu, Jan 17, 2013 at 7:07 AM, Daniele Procida <evi...@googlemail.com> wrote:
I'm re-opening an old discussion - https://groups.google.com/d/topic/django-developers/MbLD1BL5xkQ/discussion. Sorry if it all comes out weird, I'm having to do it in Google Groups.
I propose maintaining a repository of the Polls tutorial code, with each branch representing the state of the code at the end of each tutorial.
I realise that there is a danger that people might be tempted simply to checkout the code rather than type it in, following all the useful steps and mis-steps that the tutorial provides, but at the same time it would have other significant advantages that it would be a shame to forego just in order to save people from temptation, especially if they are strongly warned against it.Yes, because the best way to make sure nobody presses a button is to put a sign over it saying "Under no circumstances press this button" :-)
I can see what you're trying to achieve here, but I'm still not convinced.1) The tutorials aren't that complex; even if you did have to reproduce them from scratch, it doesn't take that long (I've done this quite a few times, so I'm speaking from experience here).
2) This is what version control is for. I'd much rather see someone do the tutorial and use version control on their own repository, rather than just pull down the latest version of a repo that contains all the code they need.Following point 2, it might be worth suggesting that people use version control during the tutorial. I'm not suggesting we turn the Django tutorial into a parallel tutorial on git, but seeding the idea in people's heads has the benefit of reinforcing best practice (you do version control everything you do, right?), and makes it easier to work around the rollback problems you describe; if they don't know what version control is, they might be encouraged to go investigate, and as a result, another code-fairy gets their wings :-)
It will help the documentation writers. It's difficult to build on the work in the tutorial if it's not easy to get where it was. For example, a new tutorial could use the Polls application to tackle logging or static files - which is what I would like to start doing now - but it's quite a bore to have to go through all the steps in all the previous tutorials just so you can start writing it.I'm definitely not convinced by this. Anyone who is in a position to be writing documentation should *definitely* be able to wrap their head around enough version control to handle this sort of thing, or be sufficiently expert to rebuild the tutorial in a couple of minutes.
I think it would be worthwhile having an official repository for this purpose.Thanks for the feedback. I'm still not convinced, but I'm always interested to hear the opinion of others. Eventually, someone (or the weight of public opinion) might convince me to change my mind
On Wednesday, January 16, 2013 4:43:14 PM UTC-8, Russell Keith-Magee wrote:Hi Daniele,2) This is what version control is for. I'd much rather see someone do the tutorial and use version control on their own repository, rather than just pull down the latest version of a repo that contains all the code they need.Following point 2, it might be worth suggesting that people use version control during the tutorial. I'm not suggesting we turn the Django tutorial into a parallel tutorial on git, but seeding the idea in people's heads has the benefit of reinforcing best practice (you do version control everything you do, right?), and makes it easier to work around the rollback problems you describe; if they don't know what version control is, they might be encouraged to go investigate, and as a result, another code-fairy gets their wings :-)There are already third-party versions of the Django tutorial that also instruct on source control and TDD. These are great, and wonderful, but I feel they overwhelm beginner Django developers with too much.