diff --git a/doc/auth.md b/doc/auth.md
index bc91257..7521f9a 100644
--- a/doc/auth.md
+++ b/doc/auth.md
@@ -10,15 +10,15 @@ Each htpasswd has few keys:
 
 - `name`: (M) used to create file and as pointee
 - `description`: (M) Used for the message box :)
-- `users`: each users is composed with 3 keys: `name` (M), `password` (M) and `state` present/absent (default: present)
+- `users`: each users is composed with 3 keys: `name` (M), `password` (M) and `state` (O) present/absent (default: present)
 - `state`: (O) present or absent. Default: present
 
-`nginx_htpasswd` should be placed in a vaut file.
+`nginx_htpasswd` should be placed in a vault file.
 
 Example
 -------
 
-```
+```yaml
 nginx_vhosts:
 # htpasswd on all vhost
   - name: test.local
diff --git a/doc/ssl.md b/doc/ssl.md
index 50c8674..52a67c6 100644
--- a/doc/ssl.md
+++ b/doc/ssl.md
@@ -27,7 +27,6 @@ OR
 - `dest_cert`: remote path where certificate is located
 - `dest_key`: remote path where key is located
 
-
 Note: `name` is used to deploy key/cert. With defaults values dans `name` = "foo", key is -> /etc/nginx/ssl/foo/foo.key
 
 Tips
@@ -35,9 +34,6 @@ Tips
 
 Deploying key/cert is not mandatory with this role. You can manage it in other place ([letsencrypt](https://letsencrypt.org/)? :)). You just need to set `dest_cert` and `dest_key`!
 
-If you set all, you can deploy your key everywhere with wanted data!
-
-
 Diffie-Hellman
 --------------
 
@@ -46,7 +42,7 @@ If you do not specify any dh param, this role auto generates it.
 Example
 -------
 
-```
+```yaml
 nginx_vhosts;
   - name: 'test-ssl.local'
     proto: ['http', 'https']
diff --git a/doc/upstream.md b/doc/upstream.md
index 14e5a5e..94d04df 100644
--- a/doc/upstream.md
+++ b/doc/upstream.md
@@ -27,3 +27,15 @@ All this params are optional. You should see [Nginx upstream doc](http://nginx.o
 - `route`
 - `slow_start`
 
+Example
+-------
+
+```yaml
+nginx_upstreams:
+  - name: 'proxy_apache'
+    servers:
+      - path: '127.0.0.1:80'
+        max_conns: 150
+        weight: 10
+        down: false
+```