Improved docs/tutorial01.txt thanks to reader suggestions

git-svn-id: http://code.djangoproject.com/svn/django/trunk@480 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/tutorial01.txt

@@ -98,16 +98,30 @@ tables. If you're interested, run the command-line client for your database and
 type ``\dt`` (PostgreSQL), ``SHOW TABLES;`` (MySQL), or ``.schema`` (SQLite) to
 display the tables.
 
-Now you're set to start doing work. You won't have to take care of this boring
-administrative stuff again.
-
 .. _`Python path documentation`: http://docs.python.org/tut/node8.html#SECTION008110000000000000000
 .. _Django's ticket system: http://code.djangoproject.com/report/1
 
 Creating models
 ===============
 
-Change into the ``myproject/apps`` directory and type this command::
+Now that your environment -- a "project" -- is set up, you're set to start
+doing work. (You won't have to take care of this boring administrative stuff
+again.)
+
+Each application you write in Django -- e.g., a weblog system, a database of
+public records or a simple poll app -- consists of a Python package, somewhere
+on your Python path, that follows a certain convention. Django comes with a
+utility that automatically generates the basic directory structure of an app,
+so you can focus on writing code rather than creating directories.
+
+In this tutorial, we'll create our poll app in the ``myproject/apps``
+directory, for simplicity. As a consequence, the app will be coupled to the
+project -- that is, Python code within the poll app will refer to
+``myproject.apps.polls``. Later in this tutorial, we'll discuss decoupling
+your apps for distribution.
+
+To create your app, change into the ``myproject/apps`` directory and type this
+command::
 
     django-admin.py startapp polls
 
@@ -141,7 +155,8 @@ In our simple poll app, we'll create two models: polls and choices. A poll has
 a question and a publication date. A choice has two fields: the text of the
 choice and a vote tally. Each choice is associated with a poll.
 
-Edit the ``polls/models/polls.py`` file so that it looks like this::
+These concepts are represented by simple Python classes. Edit the
+``polls/models/polls.py`` file so it looks like this::
 
     from django.core import meta
 
@@ -202,8 +217,8 @@ But first we need to tell our project that the ``polls`` app is installed.
 .. admonition:: Philosophy
 
    Django apps are "pluggable": You can use an app in multiple
-   projects, and you can distribute apps, because they're not tied to a given
+   projects, and you can distribute apps, because they don't have to be tied to
-   Django installation.
+   a given Django installation.
 
 Edit the myproject/settings/main.py file again, and change the ``INSTALLED_APPS``
 setting to include the string "myproject.apps.polls". So it'll look like this::
@@ -269,12 +284,12 @@ If you're interested, also run the following commands:
 Looking at the output of those commands can help you understand what's actually
 happening under the hood.
 
-Now, run this command::
+Now, run this command to create the database tables for the polls app
+automatically::
 
     django-admin.py install polls
 
-That command automatically creates the database tables for the polls app.
+Behind the scenes, all that command does is take the output of
-Behind the scenes, all it does is take the output of
 ``django-admin.py sqlall polls`` and execute it in the database pointed-to by
 your Django settings file.