diff --git a/README.adoc b/README.adoc
deleted file mode 100644
index a2773f087..000000000
--- a/README.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-// vim: ft=asciidoc
-
-image:https://travis-ci.org/kubernetes/ingress.svg?branch=master["Build Status", link="https://travis-ci.org/kubernetes/ingress"]
-image:https://coveralls.io/repos/github/kubernetes/ingress/badge.svg?branch=master["Coverage Status", link="https://coveralls.io/github/kubernetes/ingress"]
-image:https://goreportcard.com/badge/github.com/kubernetes/ingress)["Go report card", link="https://goreportcard.com/report/github.com/kubernetes/ingress"]
-
-= Ingress
-:toc: macro
-:toc-title:
-
-toc::[]
-
-== Description
-
-This repository contains controllers built around the http://kubernetes.io/docs/user-guide/ingress/[Kubernetes Ingress resource].
-It is currently in a state of flux as project maintainers port code over from https://github.com/kubernetes/contrib/tree/master/ingress[Kubernetes/contrib/ingress].
-
-== Directory Structure
-
-----
-ingress
-├── docs                  Documentation/examples
-├── controllers           Ingress Controllers
-└── vendor                Vendored dependencies
-----
diff --git a/README.md b/README.md
new file mode 100644
index 000000000..b7e9e4978
--- /dev/null
+++ b/README.md
@@ -0,0 +1,26 @@
+# Ingress
+
+[![Build Status](https://travis-ci.org/kubernetes/ingress.svg?branch=master)](https://travis-ci.org/kubernetes/ingress)
+[![Coverage Status](https://coveralls.io/repos/github/kubernetes/ingress/badge.svg?branch=master)](https://coveralls.io/github/kubernetes/ingress)
+[![Go Report Card](https://goreportcard.com/badge/github.com/kubernetes/ingress)](https://goreportcard.com/report/github.com/kubernetes/ingress)
+
+## Description
+
+This repository contains controllers built around the [Kubernetes Ingress resource](http://kubernetes.io/docs/user-guide/ingress/).
+It is currently in a state of flux as project maintainers port code over from [its previous home](https://github.com/kubernetes/contrib/tree/master/ingress).
+
+## Navigation
+
+* Learn more about using Ingress
+     * See our user documentation on [k8s.io](http://kubernetes.io/docs/user-guide/ingress/)
+     * Follow through to the respective platform specific [examples](docs/examples/README.md)
+* Write your own Ingress controller
+    * See our [developer documentation](docs/developer.md)
+* Deploy existing Ingress controllers
+    * See our [admin documentation](docs/admin.md)
+* Contribute
+    * See the [contributor guidelines](CONTRIBUTING.md)
+* Debug
+    * Peruse the [FAQ section](docs/faq.md)
+    * Ask on one of the [user-support channels](CONTRIBUTING.md#support-channels)
+
diff --git a/docs/admin.md b/docs/admin.md
new file mode 100644
index 000000000..11ea09f24
--- /dev/null
+++ b/docs/admin.md
@@ -0,0 +1 @@
+# Ingress admin guide
diff --git a/docs/developer.md b/docs/developer.md
new file mode 100644
index 000000000..3d32e0b76
--- /dev/null
+++ b/docs/developer.md
@@ -0,0 +1,3 @@
+# Ingress developer guide
+
+
diff --git a/docs/examples/README.md b/docs/examples/README.md
new file mode 100644
index 000000000..f2043884b
--- /dev/null
+++ b/docs/examples/README.md
@@ -0,0 +1,69 @@
+# Ingress examples
+
+A catalog of examples on how to run, configure and scale Ingress.
+
+## Basic cross platform
+
+Name | Description | Platform   | Complexity Level
+-----| ----------- | ---------- | ----------------
+TLS termination | terminate TLS at the ingress controller | * | Beginner
+Name based virtual hosting | `Host` header routing | * | Beginner
+Path routing | URL regex routing | * | Beginner
+Health checking | configure/optimize health checks | * | Intermediate
+Pipeline | pipeline cloud and nginx | * | Advanced
+
+## TLS
+
+Name | Description | Platform   | Complexity Level
+-----| ----------- | ---------- | ----------------
+LetsEncrypt | acquire certs via ACME protocol | * | Intermediate
+Intermediate certs | terminate TLS with intermediate certs | * | Advanced
+Client certs | client cert authentication | nginx | Advanced
+Re-encrypty | terminate, apply routing rules, re-encrypt | nginx | Advanced
+
+## Scaling
+
+Name | Description | Platform   | Complexity Level
+-----| ----------- | ---------- | ----------------
+Daemonset | run multiple controllers in a daemonset | nginx | Intermediate
+Deployment | run multiple controllers as a deployment | nginx | Intermediate
+Multi-zone | bridge different zones in a single cluster | gce | Intermediate
+Static-ip | a single ingress gets a single static ip | * | Intermediate
+Geo-routing | route to geographically closest endpoint | nginx | Advanced
+Multi-cluster | bridge Kubernetes clusters with Ingress | gce | Advanced
+
+## Algorithms
+
+Name | Description | Platform   | Complexity Level
+-----| ----------- | ---------- | ----------------
+Session stickyness | route requests consistently to the same endpoint | nginx | Advanced
+Least connections | route requests based on least connections | on-perm | Advanced
+Weights | route requrests to backends based on weights | nginx | Advanced
+
+## Routing
+
+Name | Description | Platform   | Complexity Level
+-----| ----------- | ---------- | ----------------
+Redirects | send a 301 re-direct | nginx | Intermediate
+URL-rewriting | re-write path | nginx | Intermediate
+SNI + HTTP | HTTP routing based on SNI hostname | nginx | Advanced
+SNI + TCP | TLS routing based on SNI hostname | nginx | Advanced
+
+## Auth
+
+Name | Description | Platform   | Complexity Level
+-----| ----------- | ---------- | ----------------
+Basic auth | password protect your website | nginx | Intermediate
+External auth plugin | defer to an external auth service | nginx | Intermediate
+
+## Protocols
+
+Name | Description | Platform   | Complexity Level
+-----| ----------- | ---------- | ----------------
+TCP  | TCP loadbalancing | nginx | Intermediate
+UDP | UDP loadbalancing | nginx | Intermediate
+Websockets | websockets loadbalancing | nginx | Intermediate
+HTTP/2 | HTTP/2 loadbalancing | * | Intermediate
+Proxy protocol | leverage the proxy protocol for source IP | nginx | Advanced
+
+
diff --git a/docs/faq.md b/docs/faq.md
new file mode 100644
index 000000000..35545e1f0
--- /dev/null
+++ b/docs/faq.md
@@ -0,0 +1 @@
+# Ingress FAQ