Add more explanatory text to zuul-from-scratch

Change-Id: I489fcb06d36998ba4287ce45fef1064fe6f2a3c3

doc/source/admin/centos7_setup.rst

@@ -8,8 +8,8 @@ We're going to be using CentOS 7 on a cloud server for this installation.
 Prerequisites
 -------------
 
-- Port 9000 must be open and accessible from the internet so that
+- Port 9000 must be open and accessible from the Internet so that
-  Github can communicate with the Zuul web service.
+  GitHub can communicate with the Zuul web service.
 
 Login to your environment
 -------------------------
@@ -35,6 +35,12 @@ The repositories and the packages installed from those are listed below.
 * ius-release: python35u, python35u-pip, python35u-devel
 * bigtop: zookeeper
 
+First, make sure the system packages are up to date, and then install
+some packages which will be required later.  Most of Zuul's binary
+dependencies are handled by the bindep program, but a few additional
+dependencies are needed to install bindep, and for other commands
+which we will use in these instructions.
+
 .. code-block:: console
 
    $ sudo yum update -y
@@ -48,6 +54,10 @@ The repositories and the packages installed from those are listed below.
 Install Zookeeper
 -----------------
 
+Nodepool uses Zookeeper to keep track of information about the
+resources it manages, and it's also how Zuul makes requests to
+Nodepool for nodes.
+
 .. code-block:: console
 
    $ sudo bash -c "cat << EOF > /etc/yum.repos.d/bigtop.repo

doc/source/admin/fedora27_setup.rst

@@ -8,8 +8,8 @@ We're going to be using Fedora 27 on a cloud server for this installation.
 Prerequisites
 -------------
 
-- Port 9000 must be open and accessible from the internet so that
+- Port 9000 must be open and accessible from the Internet so that
-  Github can communicate with the Zuul web service.
+  GitHub can communicate with the Zuul web service.
 
 Login to your environment
 -------------------------
@@ -25,6 +25,12 @@ To get started, ssh to your machine as the ``fedora`` user::
 Environment Setup
 -----------------
 
+First, make sure the system packages are up to date, and then install
+some packages which will be required later.  Most of Zuul's binary
+dependencies are handled by the bindep program, but a few additional
+dependencies are needed to install bindep, and for other commands
+which we will use in these instructions.
+
 ::
 
    sudo dnf update -y
@@ -35,6 +41,10 @@ Environment Setup
 Install Zookeeper
 -----------------
 
+Nodepool uses Zookeeper to keep track of information about the
+resources it manages, and it's also how Zuul makes requests to
+Nodepool for nodes.
+
 ::
 
    sudo dnf install zookeeper -y

doc/source/admin/gerrit_setup.rst

@@ -6,44 +6,52 @@ Gerrit
 Installation
 ------------
 
-Gerrit can be downloaded from the `Gerrit Code Review <https:///www.gerritcodereview.com>`_ web site, and also contains Gerrit documentation with
+Gerrit can be downloaded from the `Gerrit Code Review
-installation instructions.
+<https:///www.gerritcodereview.com>`_ web site, and also contains
+Gerrit documentation with installation instructions.
 
 Create a Zuul User
 ------------------
 
-The Gerrit documentation walks you through adding a first user, which will
+The Gerrit documentation walks you through adding a first user, which
-end up being the admin user. Once the admin user is created, and SSH access
+will end up being the admin user. Once the admin user is created, and
-has been setup for that user, you can use that account to create a new 'zuul'
+SSH access has been setup for that user, you can use that account to
-user. This user, which will be used by our Zuul installation, must have SSH
+create a new ``zuul`` user. This user, which will be used by our Zuul
-access to gerrit, and have the `stream-events <https://gerrit-review.googlesource.com/Documentation/access-control.html#global_capabilities>`_ ACL enabled.
+installation, must have SSH access to gerrit, and have the
+`stream-events <https://gerrit-review.googlesource.com/Documentation/access-control.html#global_capabilities>`_
+ACL enabled.
 
-As the admin user, create the 'zuul' user, and import an SSH key for 'zuul'::
+.. TODO: Instructions to create the ssh key used here
+
+As the admin user, create the ``zuul`` user, and import an SSH key for ``zuul``::
 
   $ cat $PUBKEY | ssh -p 29418 $USER@localhost gerrit create-account \
      --group "'Registered Users'" --ssh-key - zuul
 
-`$PUBKEY` is the location of the SSH public key for the 'zuul' user. `$USER` is
+``$PUBKEY`` is the location of the SSH public key for the ``zuul``
-the username for the admin user.
+user. ``$USER`` is the username for the admin user.
 
-The 'zuul' user should now be able to stream events::
+The ``zuul`` user should now be able to stream events::
 
   $ ssh -p 29418 zuul@localhost gerrit stream-events
 
 Configure Gerrit
 ----------------
 
-The 'zuul' user (and any other users you may create, for that matter) will
+The ``zuul`` user (and any other users you may create, for that
-need to be able to leave review votes on any project hosted in your Gerrit.
+matter) will need to be able to leave review votes on any project
-This is done with the use of Gerrit `Review Labels <https://gerrit-review.googlesource.com/Documentation/access-control.html#category_review_labels>`_.
+hosted in your Gerrit.  This is done with the use of Gerrit
-You may need to add the proper label permissions to the All-Projects project,
+`Review Labels <https://gerrit-review.googlesource.com/Documentation/access-control.html#category_review_labels>`_.
-which defines ACLs that all other projects will inherit.
+You may need to add the proper label permissions to the ``All-Projects``
+project, which defines ACLs that all other projects will inherit.
 
-Visting `Projects` -> `List` -> `All-Projects` -> `Access` in your Gerrit lets
+.. TODO: Instructions to create a Verified label?
-you see the current access permissions. In the ``Reference: refs/heads/*``
+
-section, you will need to add a permisson for the `Label Code-Review` for
+Visting `Projects` -> `List` -> `All-Projects` -> `Access` in your
-the `Registered Users` group (we added the 'zuul' user to this group when we
+Gerrit lets you see the current access permissions. In the
-created it).
+``Reference: refs/heads/*`` section, you will need to add a permisson
+for the ``Label Code-Review`` for the ``Registered Users`` group (we
+added the ``zuul`` user to this group when we created it).
 
 .. note:: The label you configure here must match the label referenced in
           your Zuul pipeline definitions. We've chosen the Code-Review label

doc/source/admin/github_setup.rst

@@ -6,8 +6,11 @@ GitHub
 Configure GitHub
 ----------------
 
-You'll need an organization in Github for this, so create one if you
+The recommended way to use Zuul with GitHub is by creating a GitHub
-haven't already.  In this example we will use `my-org`.
+App.  This allows you to easily add it to GitHub projects, and reduces
+the likelihood of running into GitHub rate limits.  You'll need an
+organization in Github for this, so create one if you haven't already.
+In this example we will use `my-org`.
 
 .. NOTE Duplicate content here and in drivers/github.rst.  Keep them
    in sync.
@@ -83,8 +86,8 @@ configured.
 
 Create two new repositories in your org.  One will hold the
 configuration for this tenant in Zuul, the other should be a normal
-project repo to use for testing.  We'll call them `zuul-test-config`
+project repo to use for testing.  We'll call them ``zuul-test-config``
-and `zuul-test`, respectively.
+and ``zuul-test``, respectively.
 
 Visit the public app page on GitHub,
 https://github.com/apps/my-org-zuul, and install the app into your org.
@@ -105,9 +108,9 @@ Edit ``/etc/zuul/main.yaml`` so that it looks like this::
            untrusted-projects:
              - my-org/zuul-test
 
-The first section, under 'zuul-git' imports the "standard library" of
+The first section, under ``zuul-git`` imports the standard library of
-Zuul jobs, a collection of jobs that can be used by any Zuul
+Zuul jobs that we configured earlier.  This adds a number of jobs that
-installation.
+you can immediately use in your Zuul installation.
 
 The second section is your GitHub configuration.
 

doc/source/admin/nodepool_install.rst

@@ -6,6 +6,10 @@ Install Nodepool
 Initial Setup
 -------------
 
+First we'll create the nodepool user and set up some directories it
+needs.  We also need to create an SSH key for Zuul to use when it logs
+into the nodes that Nodepool provides.
+
 .. code-block:: console
 
    $ sudo adduser --system nodepool --home-dir /var/lib/nodepool --create-home
@@ -18,6 +22,10 @@ Initial Setup
 Installation
 ------------
 
+Clone the Nodepool git repository and install it.  The ``bindep``
+program is used to determine any additional binary dependencies which
+are required.
+
 .. code-block:: console
 
    $ git clone https://git.zuul-ci.org/nodepool

doc/source/admin/nodepool_openstack.rst

@@ -8,7 +8,7 @@ Setup
 
 Before starting on this, you need to download your `openrc`
 configuration from your OpenStack cloud.  Put it on your server in the
-fedora user's home directory.  It should be called
+staging user's home directory.  It should be called
 ``<username>-openrc.sh``.  Once that is done, create a new keypair
 that will be installed when instantiating the servers::
 
@@ -41,7 +41,8 @@ have been filled out.
 Configuration
 -------------
 
-Inputs needed for this file:
+You'll need the following information in order to create the Nodepool
+configuration file:
 
 * cloud name / region name - from clouds.yaml
 * flavor-name

doc/source/admin/nodepool_static.rst

@@ -26,7 +26,10 @@ the command::
 Nodepool Configuration
 ----------------------
 
-Below is a sample nodepool.yaml file that sets up static nodes::
+Below is a sample Nodepool configuration file that sets up static
+nodes.  Place this file in ``/etc/nodepool/nodepool.yaml``.
+
+::
 
   zookeeper-servers:
     - host: localhost

doc/source/admin/zuul-from-scratch.rst

@@ -88,6 +88,10 @@ start Nodepool and Zuul  services with::
 Use Zuul Jobs
 -------------
 
+Zuul provides a `standard library`_ of jobs and roles.  To take advantage
+of these jobs, add the ``zuul-jobs`` repo, which is hosted by the Zuul
+project, to your system.
+
 Add to ``/etc/zuul/zuul.conf``::
 
    sudo bash -c "cat >> /etc/zuul/zuul.conf <<EOF
@@ -102,6 +106,8 @@ Restart executor and scheduler::
    sudo systemctl restart zuul-executor.service
    sudo systemctl restart zuul-scheduler.service
 
+.. _standard library: https://zuul-ci.org/docs/zuul-jobs/
+
 Setup Your Repo
 ---------------
 

doc/source/admin/zuul_install.rst

@@ -6,6 +6,10 @@ Install Zuul
 Initial Setup
 -------------
 
+First we'll create the zuul user and set up some directories it needs.
+We'll also install the SSH private key that we previously created
+during the Nodepool setup.
+
 .. code-block:: console
 
    $ sudo adduser --system zuul --home-dir /var/lib/zuul --create-home
@@ -20,6 +24,10 @@ Initial Setup
 Installation
 ------------
 
+Clone the Zuul git repository and install it.  The ``bindep`` program
+is used to determine any additional binary dependencies which are
+required.
+
 .. code-block:: console
 
    $ git clone https://git.zuul-ci.org/zuul