Re: [Django] #35502: In the tutorial we have two mysite directories, and we often see users confused by that.

[Django]

#35502: In the tutorial we have two mysite directories, and we often see users
confused by that.
--------------------------------------+------------------------------------
Reporter: Meta Petric | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: tutorial | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Changes (by Sarah Boyce):

* easy: 0 => 1
* stage: Unreviewed => Accepted
* type: Uncategorized => Cleanup/optimization

Comment:

Thank you for this Meta, I think this is a good idea 👍
--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:2>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35502: In the tutorial we have two mysite directories, and we often see users
confused by that.
--------------------------------------+------------------------------------

Reporter: Meta Petric | Owner: tabiva
Type: Cleanup/optimization | Status: assigned

Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: tutorial | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by tabiva):

* owner: nobody => tabiva
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:3>

[Django]

#35502: In the tutorial we have two mysite directories, and we often see users
confused by that.
--------------------------------------+------------------------------------
Reporter: Meta Petric | Owner: tabiva
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: tutorial | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by tabiva):

Hi folks, I should be able to fix this!
--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:4>

[Django]

#35502: In the tutorial we have two mysite directories, and we often see users
confused by that.
--------------------------------------+------------------------------------
Reporter: Meta Petric | Owner: tabiva
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: tutorial | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by tabiva):

* has_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:5>

[Django]

#35502: In the tutorial we have two mysite directories, and we often see users
confused by that.
--------------------------------------+------------------------------------
Reporter: Meta Petric | Owner: tabiva
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: tutorial | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by tabiva):

Hi folks, I have submitted a pull request to address this issue. Here is
the link to the PR: [https://github.com/django/django/pull/18271 PR].
--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:6>

[Django]

#35502: In the tutorial we have two mysite directories, and we often see users
confused by that.
--------------------------------------+------------------------------------
Reporter: Meta Petric | Owner: tabiva

Type: Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: wontfix

Keywords: tutorial | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by Sarah Boyce):

* needs_better_patch: 0 => 1
* resolution: => wontfix
* status: assigned => closed

Comment:

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 [https://forum.djangoproject.com/c/internals/5 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:7>

[Django]

#35502: In the tutorial we have two mysite directories, and we often see users
confused by that.
--------------------------------------+------------------------------------
Reporter: Meta Petric | Owner: tabiva
Type: Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: wontfix
Keywords: tutorial | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by 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:

* [https://realpython.com/django-setup/ 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
* [https://realpython.com/get-started-with-django-1/ 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.
* [https://tutorial.djangogirls.org/en/django_start_project/ 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:8>

[Django]

#35502: In the tutorial we have two mysite directories, and we often see users
confused by that.
--------------------------------------+------------------------------------
Reporter: Meta Petric | Owner: tabiva

Type: Cleanup/optimization | Status: new

Component: Documentation | Version: dev
Severity: Normal | Resolution:

Keywords: tutorial | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by Natalia Bidart):

* resolution: wontfix =>
* status: closed => new


Old description:

> 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.
>
> refferance to the turorial:
> https://docs.djangoproject.com/en/dev/intro/tutorial01/#creating-a-project

New description:

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

--
Comment:

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 [https://github.com/django/django/pull/18235 PR that Meta
submitted].
--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:9>

[Django]

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

-------------------------------------+-------------------------------------
Reporter: Meta Petric | Owner: Meta
Type: | Petric
Cleanup/optimization | Status: assigned

Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: tutorial | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):

* owner: tabiva => Meta Petric

* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:10>

[Django]

#35502: In the tutorial we have two mysite directories, and we often see users
confused by that.
-------------------------------------+-------------------------------------
Reporter: Meta Petric | Owner: Meta
Type: | Petric
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:

Keywords: tutorial | Triage Stage: Ready for
| checkin

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):

* needs_better_patch: 1 => 0
* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:11>

[Django]

#35502: In the tutorial we have two mysite directories, and we often see users
confused by that.
-------------------------------------+-------------------------------------
Reporter: Meta Petric | Owner: Meta
Type: | Petric
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:

Keywords: tutorial | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):

* needs_better_patch: 0 => 1
* stage: Ready for checkin => Accepted

--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:12>

[Django]

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

--------------------------------------+------------------------------------
Reporter: Meta Petric | Owner: Sahil390
Type: Cleanup/optimization | Status: assigned

Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: tutorial | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Sahil390):

* owner: Meta Petric => Sahil390

--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:13>

[Django]

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

-------------------------------------+-------------------------------------
Reporter: Meta Petric | Owner: Meta
Type: | Petric

Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: tutorial | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):

* owner: Sahil Narang => Meta Petric

Comment:

Hello Sahil, this ticket is still active and owned by Meta, we still need
to provide another round of reviews.
--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:14>

[Django]

#35502: In the tutorial we have two mysite directories, and we often see users
confused by that.
-------------------------------------+-------------------------------------
Reporter: Meta Petric | Owner: Meta
Type: | Petric
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:

Keywords: tutorial | Triage Stage: Ready for
| checkin

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):

* easy: 1 => 0

* needs_better_patch: 1 => 0
* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:15>

[Django]

#35502: In the tutorial we have two mysite directories, and we often see users
confused by that.
-------------------------------------+-------------------------------------
Reporter: Meta Petric | Owner: Meta
Type: | Petric

Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed

Keywords: tutorial | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by nessita <124304+nessita@…>):

In [changeset:"fc1119e8be705766b0277a0ebf8ad637f9d068c2" fc1119e8]:
{{{#!CommitTicketReference repository=""
revision="fc1119e8be705766b0277a0ebf8ad637f9d068c2"
Refs #35502 -- Clarified models.py file path in
docs/topics/db/queries.txt.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:17>

[Django]

#35502: In the tutorial we have two mysite directories, and we often see users
confused by that.
-------------------------------------+-------------------------------------
Reporter: Meta Petric | Owner: Meta
Type: | Petric
Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: tutorial | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by nessita <124304+nessita@…>):

* resolution: => fixed

* status: assigned => closed

Comment:

In [changeset:"d2c74cfb48a3d29159732fb98e3c28a53572067f" d2c74cf]:
{{{#!CommitTicketReference repository=""
revision="d2c74cfb48a3d29159732fb98e3c28a53572067f"
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+...@users.noreply.github.com>
Co-authored-by: Sarah Boyce <42296566+...@users.noreply.github.com>
Co-authored-by: Carlton Gibson <car...@noumenal.es>
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:16>

[Django]

#35502: In the tutorial we have two mysite directories, and we often see users
confused by that.
-------------------------------------+-------------------------------------
Reporter: Meta Petric | Owner: Meta
Type: | Petric
Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: tutorial | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Natalia <124304+nessita@…>):

In [changeset:"2bd546957dcc716fbef6796368e7f5a17bf0a452" 2bd5469]:
{{{#!CommitTicketReference repository=""
revision="2bd546957dcc716fbef6796368e7f5a17bf0a452"
[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+...@users.noreply.github.com>
Co-authored-by: Sarah Boyce <42296566+...@users.noreply.github.com>
Co-authored-by: Carlton Gibson <car...@noumenal.es>

Backport of d2c74cfb48a3d29159732fb98e3c28a53572067f from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:18>

[Django]

#35502: In the tutorial we have two mysite directories, and we often see users
confused by that.
-------------------------------------+-------------------------------------
Reporter: Meta Petric | Owner: Meta
Type: | Petric
Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: tutorial | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Natalia <124304+nessita@…>):

In [changeset:"a313e203e0be7831fa77a6d6b5e29f3b48f11839" a313e20]:
{{{#!CommitTicketReference repository=""
revision="a313e203e0be7831fa77a6d6b5e29f3b48f11839"
[5.1.x] Refs #35502 -- Clarified models.py file path in
docs/topics/db/queries.txt.

Backport of fc1119e8be705766b0277a0ebf8ad637f9d068c2 from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35502#comment:19>