diff --git a/doc/source/index.rst b/doc/source/index.rst
index 038a82f722..83a649b8ef 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -14,6 +14,7 @@ Contents:
    README <README.md>
    installation
    usage
+   examples
    modules
    contributing <CONTRIBUTING.md>
 
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 6f67af9302..114306a8cf 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -2,6 +2,19 @@
 Usage
 ========
 
-To use kubernetes-python-client in a project::
+The directory ``examples`` contains a few examples on how to use the client.
 
-    import kubernetes
+
+Deployments
+-----------
+
+Here is a simple usage of creating a deployment from a yaml file:
+
+
+.. literalinclude:: ../../examples/create_deployment.py
+
+
+The following example demostrates how to create, update and delete deployments
+without the need to read a file from the disk:
+
+.. literalinclude:: ../../examples/deployment_examples.py
diff --git a/examples/create_deployment.py b/examples/create_deployment.py
index 87f50eeaee..ba13440ff8 100644
--- a/examples/create_deployment.py
+++ b/examples/create_deployment.py
@@ -30,7 +30,7 @@ def main():
         k8s_apps_v1 = client.AppsV1Api()
         resp = k8s_apps_v1.create_namespaced_deployment(
             body=dep, namespace="default")
-        print("Deployment created. status='%s'" % str(resp.status))
+        print("Deployment created. status='%s'" % resp.metadata.name)
 
 
 if __name__ == '__main__':
diff --git a/examples/create_deployment_from_yaml.py b/examples/create_deployment_from_yaml.py
deleted file mode 100644
index d66a2b6b8c..0000000000
--- a/examples/create_deployment_from_yaml.py
+++ /dev/null
@@ -1,33 +0,0 @@
-# Copyright 2018 The Kubernetes Authors.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-from os import path
-
-from kubernetes import client, config, utils
-
-
-def main():
-    # Configs can be set in Configuration class directly or using helper
-    # utility. If no argument provided, the config will be loaded from
-    # default location.
-    config.load_kube_config()
-    k8s_client = client.ApiClient()
-    utils.create_from_yaml(k8s_client, "nginx-deployment.yaml")
-    k8s_api = client.AppsV1Api(k8s_client)
-    deps = k8s_api.read_namespaced_deployment("nginx-deployment", "default")
-    print("Deployment {0} created".format(deps.metadata.name))
-
-
-if __name__ == '__main__':
-    main()
diff --git a/examples/deployment_examples.py b/examples/deployment_examples.py
index 5ec656fc7d..9d354f7d3d 100644
--- a/examples/deployment_examples.py
+++ b/examples/deployment_examples.py
@@ -12,9 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from os import path
-
-import yaml
+"""
+This example shows how to work with AppsV1Api to create, modify and delete
+deployments
+"""
 
 from kubernetes import client, config
 
@@ -32,12 +33,13 @@ def create_deployment_object():
         metadata=client.V1ObjectMeta(labels={"app": "nginx"}),
         spec=client.V1PodSpec(containers=[container]))
     # Create the specification of deployment
-    spec = client.AppsV1beta1DeploymentSpec(
+    spec = client.V1DeploymentSpec(
         replicas=3,
-        template=template)
+        template=template,
+        selector={'matchLabels': {'app': 'nginx'}})
     # Instantiate the deployment object
-    deployment = client.AppsV1beta1Deployment(
-        api_version="apps/v1beta1",
+    deployment = client.V1Deployment(
+        api_version="apps/v1",
         kind="Deployment",
         metadata=client.V1ObjectMeta(name=DEPLOYMENT_NAME),
         spec=spec)
@@ -80,16 +82,16 @@ def main():
     # utility. If no argument provided, the config will be loaded from
     # default location.
     config.load_kube_config()
-    apps_v1beta1 = client.AppsV1beta1Api()
+    apps_v1 = client.AppsV1Api()
     # Create a deployment object with client-python API. The deployment we
     # created is same as the `nginx-deployment.yaml` in the /examples folder.
     deployment = create_deployment_object()
 
-    create_deployment(apps_v1beta1, deployment)
+    create_deployment(apps_v1, deployment)
 
-    update_deployment(apps_v1beta1, deployment)
+    update_deployment(apps_v1, deployment)
 
-    delete_deployment(apps_v1beta1)
+    delete_deployment(apps_v1)
 
 
 if __name__ == '__main__':