Re: make the source code of the django tutorial available ?

[gilberto dos santos alves]

very great task!

2013/9/8 German Larrain :
> I know there are different opinions on this topic but if anyone is
> interested, I created a repo for the tutorial. The idea is to have branches
> and tags that match those of the documentation.
>
> https://github.com/glarrain/django-tutorial-source-code
>
> A nice advantage of that is to be able to compare how the resulting code of
> the official tutorial changes between releases. Others are:
>
> Be able to check that the tutorial is correct (it's kind of difficult to
> spot mistakes from the documentation, either rendered or rst), i.e. the code
> works (in fact, I think I discovered a bug in the current master, which I
> will file in trac ASAP).
> Let the user compare at the end of the tutorial the code he/she typed with
> the one in the repo.
>
> Best regards,
> Germán
>
> On Wednesday, January 16, 2013 11:28:42 PM UTC-6, Russell Keith-Magee wrote:
>>
>>
>>
>> On Thu, Jan 17, 2013 at 1:17 PM, Daniel Greenfeld 
>> wrote:
>>>
>>>
>>>
>>> On Wednesday, January 16, 2013 4:43:14 PM UTC-8, Russell Keith-Magee
>>> wrote:

 Hi Daniele,

 On Thu, Jan 17, 2013 at 7:07 AM, Daniele Procida 
 wrote:
>
>
  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.
>>
>>
>> To be clear -- I'm not suggesting we try and make the Django tutorial a
>> parallel tutorial on source control. I'm just suggesting that we drop a
>> gentle hint at the start of the tutorial, to the effect of:
>>
>> "If you know how to use a source control system (like Git), you might want
>> to set up your tutorial directory as a repository.
>>
>> If you don't know how to use a source control system, don't worry. You
>> don't need to know anything about source control to complete this tutorial.
>> However, source control systems are incredibly useful tools that are used
>> widely in software development, and you'd be well advised to learn how to
>> use them."
>>
>> and then, after completing relevant blocks of work:
>>
>> "If you're using source control on this project, now would be a good time
>> to commit what you've done."
>>
>> The aim is to encourage best practice, or at least make users *aware* of
>> best practice, but leave the details up to them.
>>
>> Yours,
>> Russ Magee %-)
>>
> --
> You received this message because you are subscribed to the Google Groups
> "Django developers" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to django-developers+unsubscr...@googlegroups.com.
> To post to this group, send email to django-developers@googlegroups.com.
> Visit this group at http://groups.google.com/group/django-developers.
> For more options, visit https://groups.google.com/groups/opt_out.



-- 
gilberto dos santos alves
+55.11.98646-5049
sao paulo - sp - brasil

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at http://groups.google.com/group/django-developers.
For more options, visit https://groups.google.com/groups/opt_out.

Re: make the source code of the django tutorial available ?

[German Larrain]

I know there are different opinions on this topic but if anyone is 
interested, I created a repo for the tutorial. The idea is to have branches 
and tags that match those of the documentation.

https://github.com/glarrain/django-tutorial-source-code

A nice advantage of that is to be able to compare how the resulting code of 
the official tutorial changes between releases. Others are:

   - Be able to check that the tutorial is correct (it's kind of difficult 
   to spot mistakes from the documentation, either rendered or rst), i.e. the 
   code works (in fact, I think I discovered a bug in the current master, 
   which I will file in trac ASAP).
   - Let the user compare at the end of the tutorial the code he/she typed 
   with the one in the repo.

Best regards,
Germán

On Wednesday, January 16, 2013 11:28:42 PM UTC-6, Russell Keith-Magee wrote:
>
>
>
> On Thu, Jan 17, 2013 at 1:17 PM, Daniel Greenfeld 
>  > wrote:
>
>>
>>
>> On Wednesday, January 16, 2013 4:43:14 PM UTC-8, Russell Keith-Magee 
>> wrote:
>>
>>> Hi Daniele,
>>>
>>> On Thu, Jan 17, 2013 at 7:07 AM, Daniele Procida 
>>> wrote:
>>>

  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. 
>>
>
> To be clear -- I'm not suggesting we try and make the Django tutorial a 
> parallel tutorial on source control. I'm just suggesting that we drop a 
> gentle hint at the start of the tutorial, to the effect of:
>
> "If you know how to use a source control system (like Git), you might want 
> to set up your tutorial directory as a repository. 
>
> If you don't know how to use a source control system, don't worry. You 
> don't need to know anything about source control to complete this tutorial. 
> However, source control systems are incredibly useful tools that are used 
> widely in software development, and you'd be well advised to learn how to 
> use them."
>
> and then, after completing relevant blocks of work:
>  
> "If you're using source control on this project, now would be a good time 
> to commit what you've done."
>
> The aim is to encourage best practice, or at least make users *aware* of 
> best practice, but leave the details up to them.
>
> Yours,
> Russ Magee %-)
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at http://groups.google.com/group/django-developers.
For more options, visit https://groups.google.com/groups/opt_out.

Re: make the source code of the django tutorial available ?

[Russell Keith-Magee]

On Thu, Jan 17, 2013 at 1:17 PM, Daniel Greenfeld  wrote:

>
>
> On Wednesday, January 16, 2013 4:43:14 PM UTC-8, Russell Keith-Magee wrote:
>
>> Hi Daniele,
>>
>> On Thu, Jan 17, 2013 at 7:07 AM, Daniele Procida 
>> wrote:
>>
>>>
>>>  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.
>

To be clear -- I'm not suggesting we try and make the Django tutorial a
parallel tutorial on source control. I'm just suggesting that we drop a
gentle hint at the start of the tutorial, to the effect of:

"If you know how to use a source control system (like Git), you might want
to set up your tutorial directory as a repository.

If you don't know how to use a source control system, don't worry. You
don't need to know anything about source control to complete this tutorial.
However, source control systems are incredibly useful tools that are used
widely in software development, and you'd be well advised to learn how to
use them."

and then, after completing relevant blocks of work:

"If you're using source control on this project, now would be a good time
to commit what you've done."

The aim is to encourage best practice, or at least make users *aware* of
best practice, but leave the details up to them.

Yours,
Russ Magee %-)

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-developers@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

Re: make the source code of the django tutorial available ?

[Daniel Greenfeld]

On Wednesday, January 16, 2013 4:43:14 PM UTC-8, Russell Keith-Magee wrote:
>
> Hi Daniele,
>
> On Thu, Jan 17, 2013 at 7:07 AM, Daniele Procida 
>  > 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" :-)
>

What Russell said. 
 

> 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). 
>

If you copy/paste from an existing code base to get the tutorial working, 
then the tutorial is meaningless. Part of learning Django, Python, or 
whatever is through the experience of finding and fixing your mistakes. 
Making an official repository for the tutorial would be a disservice for 
would-be developers.
 

>
>  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.
 

>
> 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.
>

This is a fact.

In August, when we worked on refactor of page 3 of the tutorial Dave and I 
spent about 5 minutes setting up things to match. The real spent was 
gathering feedback from beginners to find their pain points with the 
tutorial.
 

>  
>
>> 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
>

I'm completely with Russ. Scratch that, I feel much stronger about this 
issue then he does. 

Zed Shaw, with LPTHW, has proven that by forcing people to type stuff out 
they learn better. You don't learn by copy/pasting or checking against a 
working implementation. It's not always fun to learn this way, but learning 
software development is a process of doing.

There are other places the tutorial needs improvement besides an official 
working implementation of the app. Off the top of my head here are a couple 
of items:

1. The new tutorial intros are nice but missing some pieces. I'll document 
this in tickets soon.
2. Page 2 of the tutorial is too long. People start copy/pasting very 
early, and attempts to teach the tutorial as a class always bog down on 
page 2. I would like to make this page shorter and move most of it to new 
intro page.

Daniel Greenfeld

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To view 

Re: make the source code of the django tutorial available ?

[Russell Keith-Magee]

Hi Daniele,

On Thu, Jan 17, 2013 at 7:07 AM, Daniele Procida 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" :-)


> 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.
>

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.

Yours,
Russ Magee %-)

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-developers@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

Re: make the source code of the django tutorial available ?

[Daniele Procida]

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.

Regards,

Daniele

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To view this discussion on the web visit 
https://groups.google.com/d/msg/django-developers/-/qAizMhCo0iQJ.
To post to this group, send email to django-developers@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

Re: make the source code of the django tutorial available ?

[Alex Ogier]

On Mon, Mar 26, 2012 at 7:28 PM, Russell Keith-Magee <
russ...@keith-magee.com> wrote:

> 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.
>

There's a middle ground: add enough metadata to the tutorial that its
instructions can be interpreted by a machine. One could imagine a build
script that parses the tutorial docs and produces four templates suitable
for 1.4's project templating system, in much the way that the ALFS
project takes
its build instructions from the Linux From Scratch documentation intended
for humans.

That said, it does seem counterproductive to give people shortcuts past the
fundamentals, especially when the fundamentals are already so carefully
curated. If you want the tutorial code as a reference, the tutorial itself
is an excellent textual description of all the changes made, so why not
just refer to that?

Best,
Alex Ogier

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-developers@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

Re: make the source code of the django tutorial available ?

[Russell Keith-Magee]

On 27/03/2012, at 4:59 AM, Michael wrote:

> Hi,
> 
> I do not know if this is the right place so sorry if not.
> I am new to Django for a few months. I love the official django tutorial and 
> I went through it. 
> However, I actually never kept the whole tutorial source code on my PC so 
> after a while, when I wanted to look at a specific thing I saw in the 
> tutorial, I just felt bad that I had to do the whole tutorial again to get 
> the whole project working.
> So I created a public repository on github 
> (https://github.com/mike87/django-tuto) with the source code of the django 
> tutorial and I have thought that it might help people like me, being between 
> beginner and intermediate that just wanna go through the tutorial sometimes.
> 
> What do you think ? Would it be nice to mention the link at the end of the 
> tutorial on the documentation ?
> Could it help beginners ?

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 %-)

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-developers@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

make the source code of the django tutorial available ?

[Michael]

Hi,

I do not know if this is the right place so sorry if not.
I am new to Django for a few months. I love the official django tutorial 
and I went through it. 
However, I actually never kept the whole tutorial source code on my PC so 
after a while, when I wanted to look at a specific thing I saw in the 
tutorial, I just felt bad that I had to do the whole tutorial again to get 
the whole project working.
So I created a public repository on github (
https://github.com/mike87/django-tuto) with the source code of the django 
tutorial and I have thought that it might help people like me, being 
between beginner and intermediate that just wanna go through the tutorial 
sometimes.

What do you think ? Would it be nice to mention the link at the end of the 
tutorial on the documentation ?
Could it help beginners ?

That was just a thought to help the community.

Michael.






-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To view this discussion on the web visit 
https://groups.google.com/d/msg/django-developers/-/EnMEVi5lr-0J.
To post to this group, send email to django-developers@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.