Opened 4 years ago

Closed 4 years ago

Last modified 4 years ago

#31385 closed Cleanup/optimization (fixed)

Improve wording of starting a new app in tutorial 1.

Reported by: Kevin Crum Owned by: Victor Moura
Component: Documentation Version: 3.0
Severity: Normal Keywords: Tutorial Ambiguity
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

In tutorial 01 (https://docs.djangoproject.com/en/3.0/intro/tutorial01/) after running start project the tutorial tells the user to add an app to the project. The tutorial uses plain English to state

Your apps can live anywhere on your Python path. In this tutorial, we’ll create our poll app right next to your manage.py file so that it can be imported as its own top-level module, rather than a submodule of mysite.

The problem lies with the use of 'right next to'.

While the tutorial does say 'top-level' that nuance can be missed by many. The tutorial also shows the directory tree of the project before adding the app and it is not entirely clear what directory one is in when they run the add app command.

I feel that if we have the language (eg the word directory) to describe where the command should be run and where the files should be this can help remove ambiguity that lives in a crucial step of the tutorial.

Change History (5)

comment:1 by Victor Moura, 4 years ago

Owner: changed from nobody to Victor Moura
Status: newassigned

I agree that the term "in the same directory" or "in the same folder" would be more clear

comment:2 by Victor Moura, 4 years ago

Component: UncategorizedDocumentation

comment:3 by Mariusz Felisiak, 4 years ago

Has patch: set
Summary: Suggestion to remove ambiguity in tutorial01 in the use of the phrase 'next to' perhaps change to 'in same directory'Improve wording of starting a new app in tutorial 1.
Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

This sounds a really minor to me, but let's have it.

PR

comment:4 by Mariusz Felisiak <felisiak.mariusz@…>, 4 years ago

Resolution: fixed
Status: assignedclosed

In 1628b35b:

Fixed #31385 -- Improved wording in tutorial 1.

comment:5 by Mariusz Felisiak <felisiak.mariusz@…>, 4 years ago

In 6de7a600:

[3.0.x] Fixed #31385 -- Improved wording in tutorial 1.

Backport of 1628b35b586e07ea47a82713192d0e4662268686 from master

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