Opened 7 months ago

Closed 2 months ago

Last modified 2 months ago

#35502 closed Cleanup/optimization (fixed)

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

Reported by: Meta Petric Owned by: Meta Petric
Component: Documentation Version: dev
Severity: Normal Keywords: tutorial
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description (last modified by Natalia Bidart)

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

Change History (19)

comment:1 by Meta Petric, 7 months ago

Description: modified (diff)
Summary: We have two mysite directories, and we often see users confused by that.In the tutorial we have two mysite directories, and we often see users confused by that.

comment:2 by Sarah Boyce, 6 months ago

Easy pickings: set
Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

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

comment:3 by tabiva, 6 months ago

Owner: changed from nobody to tabiva
Status: newassigned

comment:4 by tabiva, 6 months ago

Hi folks, I should be able to fix this!

comment:5 by tabiva, 6 months ago

Has patch: set

comment:6 by tabiva, 6 months ago

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

comment:7 by Sarah Boyce, 6 months ago

Patch needs improvement: set
Resolution: wontfix
Status: assignedclosed

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.

comment:8 by Natalia Bidart, 6 months ago

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:

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

comment:9 by Natalia Bidart, 5 months ago

Description: modified (diff)
Resolution: wontfix
Status: closednew

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.

comment:10 by Natalia Bidart, 5 months ago

Owner: changed from tabiva to Meta Petric
Status: newassigned

comment:11 by Natalia Bidart, 5 months ago

Patch needs improvement: unset
Triage Stage: AcceptedReady for checkin

comment:12 by Natalia Bidart, 4 months ago

Patch needs improvement: set
Triage Stage: Ready for checkinAccepted

comment:13 by Sahil Narang, 3 months ago

Owner: changed from Meta Petric to Sahil Narang

comment:14 by Natalia Bidart, 3 months ago

Owner: changed from Sahil Narang to Meta Petric

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

comment:15 by Natalia Bidart, 2 months ago

Easy pickings: unset
Patch needs improvement: unset
Triage Stage: AcceptedReady for checkin

comment:16 by nessita <124304+nessita@…>, 2 months ago

Resolution: fixed
Status: assignedclosed

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

comment:17 by nessita <124304+nessita@…>, 2 months ago

In fc1119e8:

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

comment:18 by Natalia <124304+nessita@…>, 2 months ago

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.

comment:19 by Natalia <124304+nessita@…>, 2 months ago

In a313e20:

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

Backport of fc1119e8be705766b0277a0ebf8ad637f9d068c2 from main.

Note: See TracTickets for help on using tickets.
Back to Top