Make Pools documentation better5.0.0.0b1

Moves a bit that was generally helpful out of a how-to
guide onto the main pools doc page.

Change-Id: I952b8e57f332fcbb727faf1bf9244d8fe6ae297c

2 files changed, 28 insertions, 28 deletions

diff --git a/doc/source/howtos/multiple-pools.rst b/doc/source/howtos/multiple-pools.rst
index c5573388..b432b861 100644
--- a/doc/source/howtos/multiple-pools.rst
+++ b/doc/source/howtos/multiple-pools.rst
@@ -14,9 +14,9 @@
     under the License.
 
 
-=================================
- How To Configure Multiple Pools
-=================================
+===============================
+How To Configure Multiple Pools
+===============================
 
 Designate supports "pools" of nameservers. A pool is a collection of
 nameservers and targets that Designate will write to and read from to
@@ -25,31 +25,8 @@ pools that you need to manage differently. For example, you might use
 separate pools to distribute tenants across some subset of your DNS
 infrastructure.
 
-
-Target vs. Nameserver
-=====================
-
-One thing that can be confusing about pools is the differentiation
-between a target and a nameserver. The target is where Designate will
-try to write the change, while a namserver is where Designate checks
-that the change exists.
-
-A great example of this is `bind's stealth master system
-<http://www.zytrax.com/books/dns/ch4/#stealth>`_. In this
-configuration, there could be a stealth master that you configure as
-your target and a set of slaves pointed to that master as your
-nameservers. Designate will write to the master and then look for the
-changes on the slaves before considering the change active.
-
-Another example would be where Designate uses an API backend such as
-DynDNS or even another Designate instance. In this situation, you will
-typically have a single target with a set of nameservers to test that
-meet your requirements.
-
-Yet another example is when using a Designate agent. In this scenario
-your agent instances are the targets and the nameservers the agent
-updates would be checked for the correct information.
-
+Read the section on :ref:`pools` to learn more about what pools are
+and what they can do.
 
 Pools Configuration
 ===================
diff --git a/doc/source/pools.rst b/doc/source/pools.rst
index bbb9a8b6..de71da86 100644
--- a/doc/source/pools.rst
+++ b/doc/source/pools.rst
@@ -52,6 +52,29 @@ but it will **not** trigger zones to be moved from one pool to another.
     Currently the only zone attribute that is accepted is the `pool_id` attribute.
     As more filters are merged there will be support for dynamic filters.
 
+Target vs. Nameserver
+=====================
+
+One thing that can be confusing about pools is the differentiation
+between a target and a nameserver. The target is where Designate will
+try to write the change, while a namserver is where Designate checks
+that the change exists.
+
+A great example of this is `bind's stealth master system
+<http://www.zytrax.com/books/dns/ch4/#stealth>`_. In this
+configuration, there could be a stealth master that you configure as
+your target and a set of slaves pointed to that master as your
+nameservers. Designate will write to the master and then look for the
+changes on the slaves before considering the change active.
+
+Another example would be where Designate uses an API backend such as
+DynDNS or even another Designate instance. In this situation, you will
+typically have a single target with a set of nameservers to test that
+meet your requirements.
+
+Yet another example is when using a Designate agent. In this scenario
+your agent instances are the targets and the nameservers the agent
+updates would be checked for the correct information.
 
 Managing Pools
 ==============