Unexpected missaccuracy on the Tutorial Chapter 3 -Django

[hectorf_lopez]

After reading the first two chapters that are very explicit and are OK. I found myself lost on the Tutorial "Writing your first Django app, part 3". Explicitly from the first section "Design your URLs". I'm new on Python world but an old C/C++ programmer. On all the exercises starting from the section "Design your URLs" I discover that the author invited to the reader to modify some files, there is not a reference on which file(s) need to be edited. How this happens?

Maybe the author writes a lot of code and forget some basics when you teach to someone to driving: you need to tell explicitly to student what path to follow up. Never let them take a decision! You need to tell when pull the gas pedal or use the breaks. They do want to know about the Transit Laws or mechanical issues. And thats what I found on this chapter that confuse me, there are a lot of code that later need to be modificated to teach something different, please cut that things and make simple.

I wish to see something easy to understand and test quickly. Forget to show me all the possibilities please! Tell explicitly which files and paths need to be modificated. Even when I look for the file "base_site.html", what at nightmare to figure out where is living. Finally I got the file.

When I reach the line that makes citation to ROOT_URLCONF = 'mysite.urls'. What I do with this line? seems important, I need to modify something? put in somewhere? Later I found that I don't have to do nothing with this... I learn something relevant? the answer is not. Please remove it.

Another issue that I found in section "Write your first view". The Author try to teach a lot of features that later need to be removed-deleted-or modify (for Godsake!) keep it simple.

I try to continue with the excercise (step by step), but here is my frustration: I can't go, because each excercise is a consecuence of the previous step. There are no citation which file need to be edited, how the whole file looks!. On previous versions of the tutorial are the same. My two cents, don't let to the reader guess... Tell him exactly what to do, don't make citation to others DJango features, this is a Tutorial and are not necessary, leave it to the user manual! keep on mind.

Before to explain something on each chapter, let show to the reader first the results; later, explain how to get it. And show us what to do to see a preview of our work.

[Julien Phalip]

Thanks a lot for your remarks and suggestions. It makes a lot of sense. The best people to write tutorials... are beginners, as it's easy for experienced people to lose perspective on the amount or type of knowledge that is appropriate for an introduction. So, your perspective is very valuable. Would you be interested in having a go at writing a patch with all the changes that you suggest? If so, then you will find some useful info here: ​https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/

[Tim Graham]

Absent a patch from the original reporter, I don't think there's much we can implement here.