Finished a first draft at Act 1

docs/_build/html/_sources/index.txt

@@ -5,6 +5,8 @@ First Django admin
 
 A step-by-step guide to creating a simple web application that empowers you to enlist reporters in data entry and refinement.
 
+You will learn just enough about the [Django](https://www.djangoproject.com/) framework to design database tables, load in data and create an administration panel for others to improve it. You will not bother with all the other web developer crap.
+
 This guide in currently being developed by `Ben Welsh <http://palewi.re/who-is-ben-welsh/>`_ and Ken Schwencke for a workshop `scheduled for March 8 <http://ire.org/conferences/nicar2015/hands-on-training/>`_ at
 the 2015 conference of the National Institute for Computer-Assisted Reporting in Atlanta.
 
@@ -119,12 +121,12 @@ pip and virtualenv
 ------------------
 
 The `pip package manager <https://pip.pypa.io/en/latest/>`_
-makes it easy to install open-source libraries that 
+makes it easy to install open-source libraries that
 expand what you're able to do with Python. Later, we will use it to install everything
-needed to create a working web application. 
+needed to create a working web application.
 
-If you don't have it already, you can get pip by following 
-`these instructions <https://pip.pypa.io/en/latest/installing.html>`_. In Windows, it's necessary to make sure that the 
+If you don't have it already, you can get pip by following
+`these instructions <https://pip.pypa.io/en/latest/installing.html>`_. In Windows, it's necessary to make sure that the
 Python ``Scripts`` directory is available on your system's ``PATH`` so it can be called from anywhere on the command line. `This screencast <http://showmedo.com/videotutorials/video?name=960000&fromSeriesID=96>`_ can help.
 
 Verify pip is installed with the following.
@@ -135,7 +137,7 @@ Verify pip is installed with the following.
 
 The `virtualenv environment manager <http://www.virtualenv.org/en/latest/>`_
 makes it possible to create an isolated corner of your computer where all the different
-tools you use to build an application are sealed off. 
+tools you use to build an application are sealed off.
 
 It might not be obvious why you need this, but it quickly becomes important when you need to juggle different tools
 for different projects on one computer. By developing your applications inside separate
@@ -169,7 +171,7 @@ Start by creating a new development environment with virtualenv. Name it after o
 
 .. code-block:: bash
 
-    # You don't have to type the "$" It's just a generic symbol 
+    # You don't have to type the "$" It's just a generic symbol
     # geeks use to show they're working on the command line.
     $ virtualenv first-django-admin
 
@@ -207,23 +209,36 @@ Now use Django's ``django-admin`` command to create a new "project" that will be
 
     $ django-admin startproject project
 
-Now jump into the project and we'll start setting it up. 
+Now jump into the project and we'll start setting it up.
 
 .. code-block:: bash
 
     $ cd project
 
 .. note::
 
-    Run the ``ls`` command, which lists the files in your current location. Wonder what all those weird files are in your new directory? We'll only need a couple for this tutorial, but you can read about all of them in the `official Django documentation <https://docs.djangoproject.com/en/1.7/intro/tutorial01/#creating-a-project>`_.
+    Run the ``ls`` command (``dir`` on Windows), which lists the files in your current location. Wonder what all those weird files are in your new directory? We'll only need a couple for this tutorial, but you can read about all of them in the `official Django documentation <https://docs.djangoproject.com/en/1.7/intro/tutorial01/#creating-a-project>`_.
 
-- Configure the settings (How much do we explain?) 
+There is a lot of `configuration <https://docs.djangoproject.com/en/1.7/intro/tutorial01/#database-setup>`_ that could be done at this point, but we're going to advance with all of the Django defaults in place.
 
-Go back one directory before you create your app, which should exist alongside the project folder.
+The first step is creating your database, which will appear as new `SQLLite <https://en.wikipedia.org/wiki/SQLite>`_ file named ``db.sqlite3``.
 
 .. code-block:: bash
 
-    $ cd ..
+    $ python manage.py migrate
+
+Now fire up Django's built-in web server.
+
+.. code-block:: bash
+
+    $ python manage.py runserver
+
+And visit `localhost:8000 <http://localhost:8000>`_ in your browser to see Django in action.
+
+.. image:: /_static/hello-django.png
+
+Act 2: Hello models
+-------------------
 
 Now let's create the app. In Django terms, an "app" is a group of code files that describe the information in your database and how it functions in the Django admin. Optionally, it describes how you output the information into web pages or APIs.
 
@@ -239,17 +254,18 @@ The startapp command just created a barebones Django app for you. Jump in and le
 
     $ cd academy
 
-- Fire up the runserver for the first time to look at default admin
-
-Act 2: Hello models
--------------------
-
 - Draft a model to match our source CSV
 - Write a management command that will load the CSV into the model
 
 Act 3: Hello admin
 ------------------
 
+Then create a new superuser with permission to edit all records.
+
+.. code-block:: bash
+
+    $ python manage.py createsuperuser
+
 - Create an admin to access and edit the new model
 - Gradually refine it so it's better
 

docs/_build/html/index.html

@@ -44,6 +44,7 @@ <h3>Navigation</h3>
   <div class="section" id="first-django-admin">
 <h1>First Django admin<a class="headerlink" href="#first-django-admin" title="Permalink to this headline">¶</a></h1>
 <p>A step-by-step guide to creating a simple web application that empowers you to enlist reporters in data entry and refinement.</p>
+<p>You will learn just enough about the [Django](<a class="reference external" href="https://www.djangoproject.com/">https://www.djangoproject.com/</a>) framework to design database tables, load in data and create an administration panel for others to improve it. You will not bother with all the other web developer crap.</p>
 <p>This guide in currently being developed by <a class="reference external" href="http://palewi.re/who-is-ben-welsh/">Ben Welsh</a> and Ken Schwencke for a workshop <a class="reference external" href="http://ire.org/conferences/nicar2015/hands-on-training/">scheduled for March 8</a> at
 the 2015 conference of the National Institute for Computer-Assisted Reporting in Atlanta.</p>
 <ul class="simple">
@@ -208,15 +209,22 @@ <h3>Python<a class="headerlink" href="#python" title="Permalink to this headline
 </div>
 <div class="admonition note">
 <p class="first admonition-title">Note</p>
-<p class="last">Run the <tt class="docutils literal"><span class="pre">ls</span></tt> command, which lists the files in your current location. Wonder what all those weird files are in your new directory? We&#8217;ll only need a couple for this tutorial, but you can read about all of them in the <a class="reference external" href="https://docs.djangoproject.com/en/1.7/intro/tutorial01/#creating-a-project">official Django documentation</a>.</p>
+<p class="last">Run the <tt class="docutils literal"><span class="pre">ls</span></tt> command (<tt class="docutils literal"><span class="pre">dir</span></tt> on Windows), which lists the files in your current location. Wonder what all those weird files are in your new directory? We&#8217;ll only need a couple for this tutorial, but you can read about all of them in the <a class="reference external" href="https://docs.djangoproject.com/en/1.7/intro/tutorial01/#creating-a-project">official Django documentation</a>.</p>
 </div>
-<ul class="simple">
-<li>Configure the settings (How much do we explain?)</li>
-</ul>
-<p>Go back one directory before you create your app, which should exist alongside the project folder.</p>
-<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span><span class="nb">cd</span> ..
+<p>There is a lot of <a class="reference external" href="https://docs.djangoproject.com/en/1.7/intro/tutorial01/#database-setup">configuration</a> that could be done at this point, but we&#8217;re going to advance with all of the Django defaults in place.</p>
+<p>The first step is creating your database, which will appear as new <a class="reference external" href="https://en.wikipedia.org/wiki/SQLite">SQLLite</a> file named <tt class="docutils literal"><span class="pre">db.sqlite3</span></tt>.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>python manage.py migrate
+</pre></div>
+</div>
+<p>Now fire up Django&#8217;s built-in web server.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>python manage.py runserver
 </pre></div>
 </div>
+<p>And visit <a class="reference external" href="http://localhost:8000">localhost:8000</a> in your browser to see Django in action.</p>
+<img alt="_images/hello-django.png" src="_images/hello-django.png" />
+</div>
+<div class="section" id="act-2-hello-models">
+<h2>Act 2: Hello models<a class="headerlink" href="#act-2-hello-models" title="Permalink to this headline">¶</a></h2>
 <p>Now let&#8217;s create the app. In Django terms, an &#8220;app&#8221; is a group of code files that describe the information in your database and how it functions in the Django admin. Optionally, it describes how you output the information into web pages or APIs.</p>
 <p>Your app will have simple models to encapsulate the data in the Academy CSV, as well as fields we are interested in filling later for data collection</p>
 <div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>django-admin startapp academy
@@ -227,18 +235,16 @@ <h3>Python<a class="headerlink" href="#python" title="Permalink to this headline
 </pre></div>
 </div>
 <ul class="simple">
-<li>Fire up the runserver for the first time to look at default admin</li>
-</ul>
-</div>
-<div class="section" id="act-2-hello-models">
-<h2>Act 2: Hello models<a class="headerlink" href="#act-2-hello-models" title="Permalink to this headline">¶</a></h2>
-<ul class="simple">
 <li>Draft a model to match our source CSV</li>
 <li>Write a management command that will load the CSV into the model</li>
 </ul>
 </div>
 <div class="section" id="act-3-hello-admin">
 <h2>Act 3: Hello admin<a class="headerlink" href="#act-3-hello-admin" title="Permalink to this headline">¶</a></h2>
+<p>Then create a new superuser with permission to edit all records.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>python manage.py createsuperuser
+</pre></div>
+</div>
 <ul class="simple">
 <li>Create an admin to access and edit the new model</li>
 <li>Gradually refine it so it&#8217;s better</li>

docs/index.rst

@@ -217,15 +217,30 @@ Now jump into the project and we'll start setting it up.
 
 .. note::
 
-    Run the ``ls`` command, which lists the files in your current location. Wonder what all those weird files are in your new directory? We'll only need a couple for this tutorial, but you can read about all of them in the `official Django documentation <https://docs.djangoproject.com/en/1.7/intro/tutorial01/#creating-a-project>`_.
+    Run the ``ls`` command (``dir`` on Windows), which lists the files in your current location. Wonder what all those weird files are in your new directory? We'll only need a couple for this tutorial, but you can read about all of them in the `official Django documentation <https://docs.djangoproject.com/en/1.7/intro/tutorial01/#creating-a-project>`_.
 
-- Configure the settings (How much do we explain?)
+There is a lot of `configuration <https://docs.djangoproject.com/en/1.7/intro/tutorial01/#database-setup>`_ that could be done at this point, but we're going to advance with all of the Django defaults in place.
 
-Go back one directory before you create your app, which should exist alongside the project folder.
+The first step is creating your database, which will appear as new `SQLLite <https://en.wikipedia.org/wiki/SQLite>`_ file named ``db.sqlite3``.
 
 .. code-block:: bash
 
-    $ cd ..
+    $ python manage.py migrate
+
+Now fire up Django's built-in web server.
+
+.. code-block:: bash
+
+    $ python manage.py runserver
+
+And visit `localhost:8000 <http://localhost:8000>`_ in your browser to see Django in action. Here's what you should see.
+
+.. image:: /_static/hello-django.png
+
+Congratulations. You've installed Django and got a blank site started up and working. Now the real work begins.
+
+Act 2: Hello models
+-------------------
 
 Now let's create the app. In Django terms, an "app" is a group of code files that describe the information in your database and how it functions in the Django admin. Optionally, it describes how you output the information into web pages or APIs.
 
@@ -241,17 +256,18 @@ The startapp command just created a barebones Django app for you. Jump in and le
 
     $ cd academy
 
-- Fire up the runserver for the first time to look at default admin
-
-Act 2: Hello models
--------------------
-
 - Draft a model to match our source CSV
 - Write a management command that will load the CSV into the model
 
 Act 3: Hello admin
 ------------------
 
+Then create a new superuser with permission to edit all records.
+
+.. code-block:: bash
+
+    $ python manage.py createsuperuser
+
 - Create an admin to access and edit the new model
 - Gradually refine it so it's better