Expand the Geo and Replication instructions

doc/howto/postgresql_replication.md

 # PostgreSQL replication
+## Prerequisites
+
+This guide assumes you've already set up one GDK instance with GitLab EE to act
+as the **primary** Geo node in a `gdk-ee` folder. If not, follow the [Set up GDK
+guide](../set-up-gdk.md#gitlab-enterprise-edition) before continuing!
+
+## Configuring replication
+
 For Gitlab Geo, you will need a master/slave database replication defined.
 There are a few extra steps to follow:
 In your primary instance (`gdk-ee`) you need to prepare the database for
-replication:
+replication. This requires the PostgreSQL server to be running, so we'll start
+the server, perform the change (via a `make` task), and then kill and restart
+the server to pick up the change:
 ```
 cd gdk-ee
+
 # terminal window 1:
 foreman start postgresql
 # terminal window 2:
 make postgresql-replication-primary
-# go back to terminal window 1 stop foreman by hitting "CTRL-C" and execute it again with:
+# terminal window 1:
+# stop foreman by hitting Ctrl-C, then restart it:
 foreman start postgresql
 ```
-You must start with a clean postgres setup on the secondary node:
+Because we'll be replicating the primary database to the secondary, we need to
+remove the secondary's PostgreSQL data folder:
 ```
 # terminal window 2:
-cd ../gdk-geo
-rm -rf postgresql
+cd gdk-geo
+rm -r postgresql
 ```
-You need to setup a symbolic link to the `postgresql` folder from the
-primary instance (`gdk-ee`):
+Now we need to add a symbolic link to the primary instance's data folder:
 ```
-# you must be in `gdk-geo` folder
+# From the gdk-geo folder:
 ln -s ../gdk-ee/postgresql postgresql-primary
 ```
@@ -39,5 +51,12 @@ Initialize a slave database and setup replication:
 ```
 # terminal window 2:
 make postgresql-replication-secondary
-# go back to terminal window 1 and stop foreman by hitting "CTRL-C"
 ```
+
+Now you can go back to **terminal window 1** and stop `foreman` by hitting
+<kbd>Ctrl-C</kbd>.
+
+## Next steps
+
+Continue to the [Post-installation
+section](../set-up-gdk.md#post-installation) of the setup guide.

doc/set-up-gdk.md

@@ -72,13 +72,13 @@ might still be running.
 Instructions to generate a developer license can be found in the
 onboarding document: https://about.gitlab.com/handbook/developer-onboarding/#gitlab-enterprise-edition-ee
-## GitLab Geo
-GitLab Geo requires two Enterprise Edition instances running most of the time.
-You can re-use your previously boostraped `gdk-ee` as your primary node and
-we suggest to bootstrap a `gdk-geo` that will act as your secondary node.
-We need to configure different ports for the new instances so they can talk to
-each other.
+### GitLab Geo
+Development on GitLab Geo requires two Enterprise Edition GDK instances running
+side-by-side. You can reuse the `gdk-ee` instance you set up in the previous
+section as your primary node, and now we'll create a secondary instance in a
+`gdk-geo` folder to act as a secondary node. We'll configure unique ports for
+the new instance so that it can run alongside the primary.
 ```
 gdk init gdk-geo
@@ -88,7 +88,9 @@ echo 3807 > webpack_port
 gdk install gitlab_repo=https://gitlab.com/gitlab-org/gitlab-ee.git
 ```
-You will need [PostgreSQL replication](./howto/postgresql_replication.md) setup before the "Post-installation" instructions.
+Now that you've installed a primary and a secondary GDK instance, follow the
+[PostgreSQL replication guide](./howto/postgresql_replication.md) before
+continuing to "Post-installation" below.
 ## Post-installation