Opened 4 months ago

Last modified 2 weeks ago

#35502 assigned Cleanup/optimization

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: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: yes 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 (14)

comment:1 by Meta Petric, 4 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, 4 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, 4 months ago

Owner: changed from nobody to tabiva
Status: newassigned

comment:4 by tabiva, 4 months ago

Hi folks, I should be able to fix this!

comment:5 by tabiva, 4 months ago

Has patch: set

comment:6 by tabiva, 4 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, 4 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, 4 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, 2 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, 2 months ago

Owner: changed from tabiva to Meta Petric
Status: newassigned

comment:11 by Natalia Bidart, 2 months ago

Patch needs improvement: unset
Triage Stage: AcceptedReady for checkin

comment:12 by Natalia Bidart, 2 months ago

Patch needs improvement: set
Triage Stage: Ready for checkinAccepted

comment:13 by Sahil Narang, 2 weeks ago

Owner: changed from Meta Petric to Sahil Narang

comment:14 by Natalia Bidart, 2 weeks 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.

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