diff --git a/docs/user-guide/namespaces.md b/docs/user-guide/namespaces.md
index 0e5c6da6fb113..d55f80a1c6c74 100644
--- a/docs/user-guide/namespaces.md
+++ b/docs/user-guide/namespaces.md
@@ -61,6 +61,8 @@ The Namespace provides a unique scope for:
 
 ## Usage
 
+Look [here](namespaces/) for an in depth example of namespaces.
+
 ### Viewing namespaces
 You can list the current namespaces in a cluster using:
 ```sh
diff --git a/examples/kubernetes-namespaces/README.md b/docs/user-guide/namespaces/README.md
similarity index 90%
rename from examples/kubernetes-namespaces/README.md
rename to docs/user-guide/namespaces/README.md
index db63e64e91ccc..31df786995f69 100644
--- a/examples/kubernetes-namespaces/README.md
+++ b/docs/user-guide/namespaces/README.md
@@ -22,11 +22,11 @@ certainly want the docs that go with that version.</h1>
 <!-- END MUNGE: UNVERSIONED_WARNING -->
 ## Kubernetes Namespaces
 
-Kubernetes _[namespaces](../../docs/user-guide/namespaces.md)_ help different projects, teams, or customers to share a Kubernetes cluster.
+Kubernetes _[namespaces](../namespaces.md)_ help different projects, teams, or customers to share a Kubernetes cluster.
 
 It does this by providing the following:
 
-1. A scope for [Names](../../docs/user-guide/identifiers.md).
+1. A scope for [Names](../identifiers.md).
 2. A mechanism to attach authorization and policy to a subsection of the cluster.
 
 Use of multiple namespaces is optional.
@@ -37,8 +37,8 @@ This example demonstrates how to use Kubernetes namespaces to subdivide your clu
 
 This example assumes the following:
 
-1. You have an [existing Kubernetes cluster](../../docs/getting-started-guides/).
-2. You have a basic understanding of Kubernetes _[pods](../../docs/user-guide/pods.md)_, _[services](../../docs/user-guide/services.md)_, and _[replication controllers](../../docs/user-guide/replication-controller.md)_.
+1. You have an [existing Kubernetes cluster](../../getting-started-guides/).
+2. You have a basic understanding of Kubernetes _[pods](../pods.md)_, _[services](../services.md)_, and _[replication controllers](../replication-controller.md)_.
 
 ### Step One: Understand the default namespace
 
@@ -70,7 +70,7 @@ One pattern this organization could follow is to partition the Kubernetes cluste
 
 Let's create two new namespaces to hold our work.
 
-Use the file [`examples/kubernetes-namespaces/namespace-dev.json`](namespace-dev.json) which describes a development namespace:
+Use the file [`namespace-dev.json`](namespace-dev.json) which describes a development namespace:
 
 ```js
 {
@@ -88,13 +88,13 @@ Use the file [`examples/kubernetes-namespaces/namespace-dev.json`](namespace-dev
 Create the development namespace using kubectl.
 
 ```shell
-$ kubectl create -f examples/kubernetes-namespaces/namespace-dev.json
+$ kubectl create -f docs/user-guide/kubernetes-namespaces/namespace-dev.json
 ```
 
 And then lets create the production namespace using kubectl.
 
 ```shell
-$ kubectl create -f examples/kubernetes-namespaces/namespace-prod.json
+$ kubectl create -f docs/user-guide/kubernetes-namespaces/namespace-prod.json
 ```
 
 To be sure things are right, let's list all of the namespaces in our cluster.
@@ -265,5 +265,5 @@ authorization rules for each namespace.
 
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
-[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/examples/kubernetes-namespaces/README.md?pixel)]()
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/namespaces/README.md?pixel)]()
 <!-- END MUNGE: GENERATED_ANALYTICS -->
diff --git a/examples/kubernetes-namespaces/namespace-dev.json b/docs/user-guide/namespaces/namespace-dev.json
similarity index 100%
rename from examples/kubernetes-namespaces/namespace-dev.json
rename to docs/user-guide/namespaces/namespace-dev.json
diff --git a/examples/kubernetes-namespaces/namespace-prod.json b/docs/user-guide/namespaces/namespace-prod.json
similarity index 100%
rename from examples/kubernetes-namespaces/namespace-prod.json
rename to docs/user-guide/namespaces/namespace-prod.json
diff --git a/examples/examples_test.go b/examples/examples_test.go
index e860ada4cbecc..55b2e599ac1c7 100644
--- a/examples/examples_test.go
+++ b/examples/examples_test.go
@@ -249,7 +249,7 @@ func TestExampleObjectSchemas(t *testing.T) {
 			"hazelcast-controller": &api.ReplicationController{},
 			"hazelcast-service":    &api.Service{},
 		},
-		"../examples/kubernetes-namespaces": {
+		"../docs/user-guide/namespaces": {
 			"namespace-dev":  &api.Namespace{},
 			"namespace-prod": &api.Namespace{},
 		},