Make it more friendly for new users by giving a better overview.

README.md

@@ -22,12 +22,22 @@ for more details.
 ## Getting started
-To start using GDK follow these three steps:
+The preferred way to use GitLab Development Kit is to install Ruby and
+dependencies on your 'native' OS. We strongly recommend the native install
+since it is much faster than a virtualized one. Due to heavy IO operations a
+virtualized installation will be much slower running the app and the tests.
+
+To do a native install:
 1. [Prepare your computer](doc/prepare.md)
-2. [Install GDK](doc/set-up-gdk.md)
-4. [Update your existing GDK installation](doc/update-gdk.md)
-3. [Learn how to use GDK](doc/howto/README.md)
+2. [Set-up GDK](doc/set-up-gdk.md)
+
+Or if you want to use [Vagrant] instead (e.g. need to do development from Windows),
+see [the instructions for our Vagrant with Virtualbox setup](vagrant.md#vagrant-with-virtualbox). If you want to use [Vagrant] with [Docker][docker engine] on Linux, see [the instructions for our Vagrant with Docker setup](vagrant.md#vagrant-with-docker).
+
+After installation [learn how to use GDK](doc/howto/README.md)
+
+If you have an old installation [update your existing GDK installation](doc/update-gdk.md)
 ## Design goals
@@ -51,7 +61,6 @@ To start using GDK follow these three steps:
 - No privilege separation between Ruby, Postgres and Redis
 - No easy upgrades
 - Need to download and compile new gems ('bundle install') on each upgrade
-- etc.
 ## License

doc/prepare.md

 # Preparing your computing environment for GDK
-The preferred way to use GitLab Development Kit is to install Ruby and
-dependencies on your 'native' OS. We strongly recommend the native install
-since it is much faster than a virtualized one. Due to heavy IO operations a
-virtualized installation will be much slower running the app and the tests.
-
-If you want to use [Vagrant] instead (e.g. need to do development from Windows),
-see [the instructions for our (experimental) Vagrant with Virtualbox setup](vagrant.md#vagrant-with-virtualbox).
-
-If you want to use [Vagrant] with [Docker][docker engine] on Linux,
-see [the instructions for our (experimental) Vagrant with Docker setup](vagrant.md#vagrant-with-docker).
-
 ## Native installation setup
 ### Prerequisites for all platforms
@@ -149,7 +138,7 @@ You may need to install Redis 2.8 or newer manually.
 Please read [the prerequisites for all platforms](#prerequisites-for-all-platforms).
 This was tested on OpenSUSE LEAP 42.1, and Tumbleweed (20161109)
- 
+
 ```
 sudo zypper dup
@@ -179,7 +168,7 @@ bundle config build.charlock_holmes "--with-icu-dir=/usr/local" --global
 Manual fix required on OpenSUSE LEAP to place redis-server in the path for non-root users:
 ```
-sudo ln -s /usr/sbin/redis-server /usr/bin/redis-server 
+sudo ln -s /usr/sbin/redis-server /usr/bin/redis-server
 ```

doc/set-up-gdk.md

@@ -102,3 +102,6 @@ Similarly, you can override the host (for example if you plan to use GDK inside
 If you want to work on GitLab CI you will need to install [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-ci-multi-runner).
 To enable the OpenLDAP server, see the OpenLDAP instructions in this readme.
+
+After installation [learn how to use GDK](doc/howto/README.md).
+

doc/vagrant.md

@@ -5,7 +5,7 @@ virtual machine to do GitLab development in. Please see the [main
 README](../README.md#installation) for instructions how to install GDK
 after you have set up your Vagrant machine.
-### Vagrant setup
+## Vagrant setup
 [Vagrant] is a tool for setting up identical development environments including
 all dependencies regardless of the host platform you are using. Vagrant will
@@ -14,7 +14,7 @@ default to using [VirtualBox], but it has many plugins for different environment
 Vagrant allows you to develop GitLab without affecting your host machine (but we
 recommend developing GitLab on metal if you can).
-#### Vagrant with Virtualbox
+### Vagrant with Virtualbox
 Vagrant can be very slow since the files are synced between the host OS and GitLab
 (testing) accesses a lot of files.
@@ -35,7 +35,7 @@ To avoid usage of slow VirtualBox shared folders we use NFS here.
 1. After the installation is done, edit the 'gitlab-workhorse' line in
    your Procfile and change `localhost:3000` to `0.0.0.0:3000`.
-#### Vagrant with Docker
+### Vagrant with Docker
 [Docker](https://www.docker.com/) is one of possible providers of Vagrant.
 Docker provider has a big advantage, as it doesn't have a big virtualisation
@@ -54,7 +54,7 @@ OSes like Windows/OSX you will have to run the entire Docker hypervisor in a VM
 1. After the installation is done, edit the 'gitlab-workhorse' line in
    your Procfile and change `localhost:3000` to `0.0.0.0:3000`.
-#### Vagrant development details
+### Vagrant development details
 - Open the development environment by running `vagrant up` & `vagrant ssh`
   (from an elevated command prompt if on Windows).
@@ -68,7 +68,7 @@ OSes like Windows/OSX you will have to run the entire Docker hypervisor in a VM
 - When you want to shutdown Vagrant run `exit` from the guest OS and then
   `vagrant halt` from the host OS.
-#### Vagrant troubleshooting
+### Vagrant troubleshooting
 - On some setups the shared folder will have the wrong user. This is detected
   by the Vagrantfile and you should `sudo su - build` to switch to the correct
@@ -86,3 +86,7 @@ OSes like Windows/OSX you will have to run the entire Docker hypervisor in a VM
 [Vagrant]: https://www.vagrantup.com
 [VirtualBox]: https://www.virtualbox.org
 [Docker Engine]: https://www.docker.com/products/docker-engine
+
+## Next step
+
+After installation [learn how to use GDK](doc/howto/README.md).