diff --git a/README.md b/README.md
index 7d436e68b..45bf1b358 100644
--- a/README.md
+++ b/README.md
@@ -10,33 +10,68 @@
 dotnet add package KubernetesClient
 ```
 
-# Generating the Client Code
+# Usage
 
-## Prerequisites
+## Authentication/Configuration
+You should be able to use an standard KubeConfig file with this library,
+see the `BuildConfigFromConfigFile` function below. Most authentication
+methods are currently supported, but a few are not, see the 
+[known-issues](https://github.com/kubernetes-client/csharp#known-issues)
 
-You'll need a Linux machine with Docker.
+You should also be able to authenticate using the in-cluster service
+account using the `InClusterConfig` function shown below.
 
-The generated code works on all platforms supported by .NET or .NET Core.
+## Sample Code
 
-Check out the generator project into some other directory
-(henceforth `$GEN_DIR`)
+### Creating the client
+```c#
+// Load from the default kubeconfig on the machine.
+var config = KubernetesClientConfiguration.BuildConfigFromConfigFile();
 
-```bash
-cd $GEN_DIR/..
-git clone https://github.com/kubernetes-client/gen
+// Load from a specific file:
+var config = KubernetesClientConfiguration.BuildConfigFromConfigFile(Environment.GetEnvironmentVariable("KUBECONFIG"));
+
+// Load from in-cluster configuration:
+var config = KubernetesClientConfiguration.InClusterConfig()
+
+// Use the config object to create a client.
+var client = new Kubernetes(config);
 ```
 
-## Generating code
+### Listing Objects
+```c#
+var namespaces = client.ListNamespace();
+foreach (var ns in namespaces.Items) {
+    Console.WriteLine(ns.Metadata.Name);
+    var list = client.ListNamespacedPod(ns.Metadata.Name);
+    foreach (var item in list.Items)
+    {
+        Console.WriteLine(item.Metadata.Name);
+    }
+}
+```
 
-```bash
-# Where REPO_DIR points to the root of the csharp repository
-cd ${REPO_DIR}/csharp/src/KubernetesClient
-${GEN_DIR}/openapi/csharp.sh generated ../csharp.settings
+### Creating and Deleting Objects
+```c#
+var ns = new V1Namespace
+{
+    Metadata = new V1ObjectMeta
+    {
+        Name = "test"
+    }
+};
+
+var result = client.CreateNamespace(ns);
+Console.WriteLine(result);
+
+var status = client.DeleteNamespace(ns.Metadata.Name, new V1DeleteOptions());
 ```
 
-# Usage
+## Examples
+
+There is extensive example code in the [examples directory](https://github.com/kubernetes-client/csharp/tree/master/examples).
 
-## Running the Examples
+### Running the Examples
 
 ```bash
 git clone git@github.com:kubernetes-client/csharp.git
@@ -80,6 +115,30 @@ dotnet restore
 dotnet test
 ```
 
+# Generating the Client Code
+
+## Prerequisites
+
+You'll need a Linux machine with Docker.
+
+The generated code works on all platforms supported by .NET or .NET Core.
+
+Check out the generator project into some other directory
+(henceforth `$GEN_DIR`)
+
+```bash
+cd $GEN_DIR/..
+git clone https://github.com/kubernetes-client/gen
+```
+
+## Generating code
+
+```bash
+# Where REPO_DIR points to the root of the csharp repository
+cd ${REPO_DIR}/csharp/src/KubernetesClient
+${GEN_DIR}/openapi/csharp.sh generated ../csharp.settings
+```
+
 ## Contributing
 
 Please see [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on how to contribute.