In the tutorial we have two mysite directories, and we often see users confused by that.

[Meta Petric]

The tutorial instructs you to make a mysite directory and in that directory make another one with the same name. We could resolve this confusion by changing the start project command from : django-admin startproject mysite to django-admin startproject mysite djangotutorial. That way it becomes clear to which directory the tutorial is referring to.

There was a ticket #22042 (confused in tutorial 03 about location of mysite/urls.py) that has already been closed, but maybe this solution will be beneficial.

Reference to the tutorial: ​https://docs.djangoproject.com/en/dev/intro/tutorial01/#creating-a-project

[Sarah Boyce]

Thank you for this Meta, I think this is a good idea 👍

[tabiva]

Hi folks, I should be able to fix this!

[tabiva]

Hi folks, I have submitted a pull request to address this issue. Here is the link to the PR: ​PR.

[Sarah Boyce]

Having read through the changes, I am no longer convinced this is the best way forward as django-admin startproject mysite is the simplist version of running the startproject command and having this documented in the intro tutorial has some benefits. This makes me think that a wider discussion is needed. If you wish to progress this change, please discuss it on the ​forum also to confirm where exactly beginners get confused as maybe this isn't the right way to fix it.

tabvia please note that you your PR is missing some file header updates for the code snippets in the tutorial.

[Natalia Bidart]

I've been investigating other resources to check what they do, and I think there is enough variation/confusion that we should take a stance and improve our tutorial. Some links showing how startproject is used:

• ​Your First Steps With Django: Set Up a Django Project uses django-admin startproject setup but it has a long and arguably confusing/distracting note about why the duplicated setup folder
• ​Get Started With Django: Build a Portfolio App uses django-admin startproject personal_portfolio . but it needs to clarify that Don’t forget to add the dot (.) at the end of the command above. since it can be easily missed.
• ​Django Girls Tutorial: Your first Django project! uses django-admin startproject mysite . and it also needs to clarify how crucial the dot is.

I'll go back to the first PR created for this issue and review with this in mind, will post updates afterwards.

[Natalia Bidart]

After some further thinking, and considering all the discussion that took place during the Improving the Intro Documentation workshop at DjangoCon Europe, I think that this ticket is worth pursuing. I'm re-opening to iterate over the ​PR that Meta submitted.

[Natalia Bidart]

Hello Sahil, this ticket is still active and owned by Meta, we still need to provide another round of reviews.

[nessita <124304+nessita@…>]

In d2c74cf:

Fixed #35502 -- Removed duplication of "mysite" directory name in intro docs.

Reorganized intro docs when explaining django-admin startproject to prevent
confusion when using "mysite" as both the top-level directory and the Django
project directory name.

Co-authored-by: Natalia <124304+nessita@…>
Co-authored-by: Sarah Boyce <42296566+sarahboyce@…>
Co-authored-by: Carlton Gibson <carlton@…>

[nessita <124304+nessita@…>]

In fc1119e8:

Refs #35502 -- Clarified models.py file path in docs/topics/db/queries.txt.

[Natalia <124304+nessita@…>]

In 2bd5469:

[5.1.x] Fixed #35502 -- Removed duplication of "mysite" directory name in intro docs.

Reorganized intro docs when explaining django-admin startproject to prevent
confusion when using "mysite" as both the top-level directory and the Django
project directory name.

Co-authored-by: Natalia <124304+nessita@…>
Co-authored-by: Sarah Boyce <42296566+sarahboyce@…>
Co-authored-by: Carlton Gibson <carlton@…>

Backport of d2c74cfb48a3d29159732fb98e3c28a53572067f from main.

[Natalia <124304+nessita@…>]

In a313e20:

[5.1.x] Refs #35502 -- Clarified models.py file path in docs/topics/db/queries.txt.

Backport of fc1119e8be705766b0277a0ebf8ad637f9d068c2 from main.