Start howto/README.md

README.md

 # GitLab Development Kit
-The GDK runs a GitLab development environment isolated in a directory.
-This project uses Foreman to run dedicated Postgres and Redis processes for
-GitLab development. All data is stored inside the gitlab-development-kit
-directory. All connections to supporting services go through Unix domain
-sockets to avoid port conflicts.
+Configure and manage a [GitLab](https://about.gitlab.com) development environment.
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
@@ -61,6 +57,16 @@ sockets to avoid port conflicts.
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
+## Overview
+
+GitLab Development Kit (GDK) provides a collection of scripts and other resources to install and manage a GitLab installation for development purposes. The source code of GitLab is spread over multiple repositories and it requires Ruby, Go, Postgres/MySQL, Redis and more to run. GDK helps you install and configure all these different components, and start/stop them when you work on GitLab.
+
+To start using GDK follow these three steps:
+
+- [Prepare your computer](doc/prepare.md)
+- [Install GDK](doc/set-up-gdk.md)
+- [Learn how to use GDK](doc/howto/README.md)
+
 ## Design goals
 - Get the user started, do not try to take care of everything
@@ -87,22 +93,6 @@ sockets to avoid port conflicts.
 ## Development
-When doing development, you will need one shell session (terminal window)
-running Postgres and Redis, and one or more other sessions to work on GitLab
-itself.
-
-### Example
-
-First start Postgres and Redis.
-
-```
-# current directory: gitlab-development-kit
-./run
-```
-
-Now you can go to http://localhost:3000 in your browser.
-The development login credentials are `root` and `5iveL!fe`
-
 ### Running the tests
 In order to run the test you can use the following commands:

doc/howto/README.md

+# How to use GitLab Development Kit
+
+- [Browse your development GitLab server](browse.md)
+- [GitLab developer documentation](http://docs.gitlab.com/ce/development/README.html)

doc/howto/browse.md

+# Browse your development GitLab server
+
+If you just want to browse your local GitLab installation this is the
+quickest way to do it.
+
+```
+cd gitlab-development-kit
+./run
+```
+
+Open [localhost:3000](http://localhost:3000) in your web browser. It
+may take a few seconds for GitLab to boot in development mode. Once
+the sign-in page is there, log in with user `root` and password
+`5iveL!fe`.
+
+You can shut down GDK in your terminal with Ctrl-C.
\ No newline at end of file