--- a/README.txt	Fri Feb 04 08:11:07 2011 -0800
+++ b/README.txt	Fri Feb 04 08:28:21 2011 -0800
@@ -10,18 +10,19 @@
 autobot is a continuous integration solution for the Automation and
 Tools Team.  We have a lot of software.  We're really talented, so
 usually it doesn't break.  But we're not infalliable.  Our robot ally,
-autobot, is there to test things for us.  Let's me autobot!
+autobot, is there to test things for us.  Let's meet autobot!
 
 
 Installing autobot
 ------------------
 
-autobot may be installed using the Install script::
+autobot may be installed using the install script::
 
  curl http://k0s.org/mozilla/hg/autobot/raw-file/tip/INSTALL.sh | bash
 
 This will create a virtualenv and install autobot for development
-($VIRTUAL_ENV/src/autobot). 
+($VIRTUAL_ENV/src/autobot).  You can also use the script as
+instructions and install it in the same manner as any other python package.
 
 
 Setting up a buildmaster and slave
@@ -33,11 +34,14 @@
 You can create a master-slave pair by running ``create-autobot`` after
 activating the virtualenv. This is mostly useful for autobot
 development. The scripts ``create-autobot-master`` and 
-``create-autobot-slave`` are also available.  The scripts will prompt you
-for a factory. The factories are from ``autobot.projects`` and its
-subdirectories.  You can list the available factories with
-``create-autobot --list-factories`` (or ``create-autobot-master
---list-factories``).
+``create-autobot-slave`` are also available and are more useful for
+production, as normally you will not want to keep the master and the
+slave on the same machine except for development and testing.  The
+scripts will prompt you for a factory or you can specify one or more
+from the commandline using ``--factory`` or ``-f``. The factories are
+from ``autobot.projects`` and its subdirectories.  You can list the
+available factories with ``create-autobot --list-factories`` (or 
+``create-autobot-master --list-factories``).
 
 Running ``create-autobot --help`` will give the variables you can set
 when it makes a new bot for you (``create-autobot-master`` and
@@ -45,20 +49,21 @@
 ``create-autobot`` being a superset of these).
 
 If you don't specify a variable, the default will be used to create
-your particular bot.  You can (probably) change it later.
+your particular bot.  You can change these in the resultant
+configuration later.
 
  
 Using autobot
 -------------
 
 The buildmaster and buildslave are started with 
-``buildbot start master`` and ``buildslave stop slave``. Respective
-``stop`` commands also exist.  If you used the ``create-autobot``
-command the generated bot will have a ``restart_buildbot.py`` script
-that will stop and start both the master and slave and (if debug is
-set) remove the log as well.
+``buildbot start master`` and ``buildslave stop slave`` from the bot's
+directories. Respective ``stop`` commands also exist.  If you used the
+``create-autobot`` command the generated bot will have a
+``restart_buildbot.py`` script that will stop and start both the
+master and slave and (if debug is set) remove the log as well.
 
-The generated ``master.cfg`` file reads values from an ``master.ini``
+The generated ``master.cfg`` file reads values from a ``master.ini``
 file in the same directory.  The master.ini contains a number of
 different sections:
 
@@ -66,13 +71,13 @@
   as well as default settings for slaves
 * sections like ``[slave:slavename]`` indicate a slave of name
   ``slavename``
-* other sections are construction parameters for factories
+* all other sections are construction parameters for factories
 
 The format of the ``.ini`` file is detailed in the subsequent
-section.  You may change the .ini file used by editing the
+section.  You may change which .ini file is used by editing the
 ``master.cfg`` file, or, if for whatever reason you don't want to use
-an .ini file you can construct the appropriate configuration therein
-yourself.
+an .ini file as a driver you can construct the appropriate
+configuration therein yourself.
 
 An overview of the build status is detailed at the waterfall display,
 by default at http://localhost:8010/waterfall . To force a build,
@@ -80,13 +85,14 @@
 towards the bottom.
 
 It is important to remember that continuous integration is a safety
-net, not a first line of defense.  In other words, continue to check your code
-*before* sending it to autobot.
+net, not a first line of defense.  In other words, continue to check
+your code *before* sending it to autobot.
+
 
 .ini file format
 ----------------
 
-As stated above, a ``master.ini`` file contains three different kinds
+As stated above, a ``master.ini`` file contains three different types
 of sections:
 
 * ``[:master:]`` contains the top level configuration for the master
@@ -117,25 +123,29 @@
 ``slave:`` parameters for each slave:
 
 * password: each slave *must* have a password.  Unless there's a
-  reason to have a password per slave, its probably better to put this
-  in the ``:master:`` section
+  reason to have a different password per slave, its probably better
+  to put this in the ``:master:`` section
 
 * factories: space-separated list of factories to run on that slave.
   If the special value ``*`` is used, all factories will be run.  You
   can view the factories available with 
   ``create-autobot --list-factories``. The factory name corresponds to
-  the directory (or module) name in ``autobot.projects``.
+  the directory (or module) name in ``autobot.projects``.  If
+  every slave is meant to run the same factories, you can put this in
+  the ``:master:`` section
 
-* os: the operating system of the slave. Should be one of linux, win,
-  or mac (though see TODO about future use of MozInfo making this
-  obselescent). You probably *shouldn't* have a default key for this
-  in the ``:master:`` section (though autobot won't try to stop you!).
+* os: the operating system of the slave. Should be one of ``linux``, 
+  ``win``, or ``mac`` (though see TODO about future use of MozInfo
+  making this obselescent). You probably *shouldn't* have a default
+  key for this in the ``:master:`` section (though autobot won't try
+  to stop you!).
 
 ----
 
-factory sections:  Each parameter in a factory section is used as a
-constructor (``__init__``) keyword argument when they are created in
-the ``master.cfg``. So a factory section like::
+factory sections:  All other sections are used to build the factories.
+Each parameter in a factory section is used as a constructor
+(``__init__``) keyword argument when they are created in the
+``master.cfg``. So a factory section like:: 
 
  [foo]
  bar = fleem
@@ -171,11 +181,24 @@
 to see this location).
 
 
+
 Adding a New Project
 --------------------
 
 Occassionally, you'll need to add a new project to test.  You can add
-a ``__init__.py`` file
+a ``__init__.py`` file to a directory under ``autobot.projects`` and,
+if you have a factory therein, autobot will find it and add it to the
+list of factories it knows about.
+
+There is also a script, ``create-autobot-project``, that can create
+this stub for you::
+
+ Usage: create-autobot-project [options] project <output>
+
+``project`` is the name of the project and ``output``, if specified,
+is the path of the file to create.  If output is not specified, it
+will find its way to a directory named for the project under
+``autobot.projects``.
 
 
 Is your autobot being feisty?