diff --git a/docs/acme-cert.yaml b/docs/acme-cert.yaml
new file mode 100644
index 000000000..10fb99075
--- /dev/null
+++ b/docs/acme-cert.yaml
@@ -0,0 +1,36 @@
+apiVersion: certmanager.k8s.io/v1alpha1
+kind: Certificate
+metadata:
+  name: certmanager-k8s-co
+spec:
+  secretName: certmanager-k8s-co
+  issuer: letsencrypt-staging
+  domains:
+  - certmanager.k8s.co
+  acme:
+    config:
+    - domains:
+      - certmanager.k8s.co
+      http-01:
+        # note: using an ingress doesn't currently work
+        ingress: certmanager-k8s-co
+status:
+  acme: {}
+---apiVersion: certmanager.k8s.io/v1alpha1
+kind: Certificate
+metadata:
+  name: certmanager-k8s-co
+spec:
+  secretName: certmanager-k8s-co
+  issuer: letsencrypt-staging
+  domains:
+  - certmanager2.k8s.co
+  acme:
+    config:
+    - domains:
+      - certmanager.k8s.co
+      http-01:
+        # note: using an ingress class doesn't currently work
+        ingressClass: nginx
+status:
+  acme: {}
diff --git a/docs/acme-issuer.yaml b/docs/acme-issuer.yaml
new file mode 100644
index 000000000..5b67fee50
--- /dev/null
+++ b/docs/acme-issuer.yaml
@@ -0,0 +1,18 @@
+apiVersion: certmanager.k8s.io/v1alpha1
+kind: Issuer
+metadata:
+  name: letsencrypt-staging
+spec:
+  acme:
+    server: https://acme-staging.api.letsencrypt.org/directory
+    email: james@jetstack.io
+    privateKey: le-staging
+    # dns-01 config options
+    dns-01:
+      providers:
+      - name: clouddns-staging
+        clouddns:
+          serviceAccount: service-account-secret-staging
+          project: googles-corp-project
+status:
+  ready: true
\ No newline at end of file
diff --git a/docs/cert-manager.yaml b/docs/cert-manager.yaml
new file mode 100644
index 000000000..847d0f636
--- /dev/null
+++ b/docs/cert-manager.yaml
@@ -0,0 +1,33 @@
+apiVersion: apps/v1beta1
+kind: Deployment
+metadata:
+  name: cert-manager
+spec:
+  replicas: 1
+  strategy:
+    type: Recreate
+  template:
+    metadata:
+      labels:
+        app: cert-manager
+    spec:
+      containers:
+      - name: cert-manager
+        image: quay.io/jetstack/cert-manager:canary
+        imagePullPolicy: Always
+        ports:
+        - name: http
+          containerPort: 8080
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: cert-manager
+spec:
+  type: LoadBalancer
+  ports:
+  - name: http
+    port: 80
+    targetPort: 8080
+  selector:
+    app: cert-manager
diff --git a/docs/certificate.yaml b/docs/certificate.yaml
deleted file mode 100644
index 57f717195..000000000
--- a/docs/certificate.yaml
+++ /dev/null
@@ -1,63 +0,0 @@
-# certificate resource request for google.com using letsencrypt issuer
-apiVersion: certmanager.k8s.io/v1alpha1
-kind: Certificate
-metadata:
-  name: production-crt
-spec:
-  secret: production-crt
-  issuer: letsencrypt-prod
-  domains:
-  - www.google.com
-  acme:
-    http-01:
-      # if the ingress resource already exists, we modify it to add our path
-      # instead of creating our own ingress resource (to support gce). if this
-      # is blank, a temporary ingress resource will be used
-      ingress: google-com
-      # only required when
-      ingressClass: nginx
-status:
-  state: Pending
----
-# letsencrypt issuer resource
-apiVersion: certmanager.k8s.io/v1alpha1
-kind: Issuer
-metadata:
-  name: letsencrypt-prod
-spec:
-  acme:
-    url: https://letsencrypt-prod.org
-    email: james@jetstack.io
-    privateKey: james-letsencrypt-prod
-status:
-  ready: true
----
-# certificate resource request for google.com using letsencrypt issuer
-apiVersion: certmanager.k8s.io/v1alpha1
-kind: Certificate
-metadata:
-  name: vault-crt
-spec:
-  secret: vault-crt
-  issuer: vault-prod
-  domains:
-  - www.yahoo.com
-  vault:
-    role: serving
-status:
-  state: Pending
----
-# vault issuer resource
-apiVersion: certmanager.k8s.io/v1alpha1
-kind: Issuer
-metadata:
-  name: vault-prod
-spec:
-  vault:
-    url: https://vault.service.svc.cluster.local
-    path: pki/prod-ca/
-    credentials:
-      token:
-        secretName: vault-token
-status:
-  ready: true
diff --git a/docs/test-crt.yaml b/docs/test-crt.yaml
deleted file mode 100644
index 76a326bf4..000000000
--- a/docs/test-crt.yaml
+++ /dev/null
@@ -1,17 +0,0 @@
-apiVersion: certmanager.k8s.io/v1alpha1
-kind: Certificate
-metadata:
-  name: certmanager-k8s-co
-spec:
-  secretName: certmanager-k8s-co
-  issuer: letsencrypt-staging
-  domains:
-  - certmanager.k8s.co
-  acme:
-    config:
-    - domains:
-      - certmanager.k8s.co
-      http-01:
-        ingress: certmanager-k8s-co
-status:
-  acme: {}
diff --git a/docs/vault-example.yaml b/docs/vault-example.yaml
new file mode 100644
index 000000000..914257270
--- /dev/null
+++ b/docs/vault-example.yaml
@@ -0,0 +1,31 @@
+# NOTE: These resources do not currently work and hare just here as a vision
+# of how vault may be supported
+apiVersion: certmanager.k8s.io/v1alpha1
+kind: Certificate
+metadata:
+  name: facebook-crt
+spec:
+  secret: facebook-crt
+  issuer: vault-staging
+  domains:
+  - www.facebook.com
+  - facebook.com
+status:
+  state: Ready
+---
+# vault issuer resource
+apiVersion: certmanager.k8s.io/v1alpha1
+kind: Issuer
+metadata:
+  name: vault-staging
+spec:
+  vault:
+    url: https://vault.vault.svc.cluster.local
+    path: pki/prod-ca/
+    role: http-server
+    auth:
+      token:
+        secretName: vault-staging-token
+status:
+  ready: true
+---
\ No newline at end of file