Reorganize docs into user/admin guide
Refresh the user and admin guide for v3 changes, and reorganize into
a narrative structure which makes more sense for v3.
Change-Id: I4ac3b18d5ed33b0fea4e2ef0318b19bfc3447ccc
diff --git a/doc/source/admin/quick-start.rst b/doc/source/admin/quick-start.rst
new file mode 100644
index 0000000..780496b
--- /dev/null
+++ b/doc/source/admin/quick-start.rst
@@ -0,0 +1,120 @@
+Quick Start Guide
+=================
+
+This provides a very simple overview of Zuul. It is recommended to
+read the following sections for more details.
+
+Install Zuul
+------------
+
+You can get zuul from pypi via::
+
+ pip install zuul
+
+Zuul Components
+---------------
+
+Zuul provides the following components:
+
+ - **zuul-scheduler**: The main Zuul process. Handles receiving
+ events, executing jobs, collecting results and posting reports.
+ Coordinates the work of the other components.
+
+ - **zuul-merger**: Scale-out component that performs git merge
+ operations. Zuul performs a large number of git operations in
+ the course of its work. Adding merger processes can help speed
+ Zuul's processing. This component is optional (zero or more of
+ these can be run).
+
+ - **zuul-executor**: Scale-out component for executing jobs. At
+ least one of these is required. Depending on system
+ configuration, you can expect a single executor to handle up to
+ about 100 simultaneous jobs. Can handle the functions of a
+ merger if dedicated mergers are not provided. One or more of
+ these must be run.
+
+ - **gearman**: optional builtin gearman daemon provided by zuul-scheduler
+
+External components:
+
+ - **gearman**: A gearman daemon if the built-in daemon is not used.
+
+ - **zookeeper**: A zookeeper cluster (or single host) for
+ communicating with Nodepool.
+
+ - **nodepool**: Provides nodes for Zuul to use when executing jobs.
+
+
+Zuul Setup
+----------
+
+At minimum you need to provide **zuul.conf** and **main.yaml** placed
+in **/etc/zuul/**. The following example uses the builtin gearman
+service in Zuul, and a connection to Gerrit.
+
+**zuul.conf**::
+
+ [zuul]
+ tenant_config=/etc/zuul/main.yaml
+
+ [gearman_server]
+ start=true
+
+ [gearman]
+ server=127.0.0.1
+
+ [connection gerrit]
+ driver=gerrit
+ server=git.example.com
+ port=29418
+ baseurl=https://git.example.com/gerrit/
+ user=zuul
+ sshkey=/home/zuul/.ssh/id_rsa
+
+See :ref:`components` and :ref:`connections` for more details.
+
+The following tells Zuul to read its configuration from and operate on
+the *example-project* project:
+
+**main.yaml**::
+
+ - tenant:
+ name: example-tenant
+ source:
+ gerrit:
+ untrusted-projects:
+ - example-project
+
+Starting Zuul
+-------------
+
+You can run any zuul process with the **-d** option to make it not
+daemonize. It's a good idea at first to confirm there's no issues with
+your configuration.
+
+To start, simply run::
+
+ zuul-scheduler
+
+Once run you should have two zuul-scheduler processes (if using the
+built-in gearman server, or one process otherwise).
+
+Before Zuul can run any jobs, it needs to load its configuration, most
+of which is in the git repositories that Zuul operates on. Start an
+executor to allow zuul to do that::
+
+ zuul-executor
+
+Zuul should now be able to read its configuration from the configured
+repo and process any jobs defined therein.
+
+Troubleshooting
+---------------
+
+You can use telnet to connect to gearman to check which Zuul
+components are online::
+
+ telnet <gearman_ip> 4730
+
+Useful commands are **workers** and **status** which you can run by just
+typing those commands once connected to gearman.