diff --git a/guide/troubleshooting.md b/guide/troubleshooting.md
index 35afabbb..53d20681 100644
--- a/guide/troubleshooting.md
+++ b/guide/troubleshooting.md
@@ -1,5 +1,65 @@
 # Troubleshooting guide
 
+## Timeouts
+
+Default timeouts are configured at the HTTP level and must be set both on the gateway and the function.
+
+**Your function**
+
+You can also enforce a hard-timeout for your function with the `hard_timeout` environmental variable.
+
+For watchdog configuration see the [README](https://github.com/openfaas/faas/tree/master/watchdog).
+
+The best way to set the timeout is in the YAML file generated by the `faas-cli`.
+
+Example Go app that sleeps for (10 seconds):
+
+```
+provider:
+  name: faas
+  gateway: http://localhost:8080
+
+functions:
+  sleepygo:
+    lang: go
+    handler: ./sleepygo
+    image: alexellis2/sleeps-for-10-seconds
+    environment:
+        read_timeout: 20
+        write_timeout: 20
+```
+
+handler.go
+
+```
+package function
+
+...
+
+func Handle(req []byte) string {
+	time.Sleep(time.Second * 10)
+	return fmt.Sprintf("Hello, Go. You said: %s", string(req))
+}
+```
+
+**Gateway**
+
+For the gateway set the following environmental variables:
+
+```
+read_timeout: 30
+write_timeout: 30
+```
+
+The default for both is "8" - seconds. In the example above "30" means 30 seconds.
+
+If on Kubernetes, set a matching timeout for the faas-netesd controller too:
+
+```
+read_timeout: 30
+write_timeout: 30
+```
+
 ## Healthcheck
 
 Most problems reported via GitHub or Slack stem from a configuration problem or issue with a function. Here is a checklist of things you can try before digging deeper:
@@ -77,16 +137,6 @@ If you're using the async stack remove it this way:
 $ kubectl delete -f faas.async.yml,monitoring.yml,rbac.yml,nats.yml
 ```
 
-## Timeouts
-
-Default timeouts are configured at the HTTP level for the gateway and watchdog. You can also enforce a hard-timeout for your function.
-
-For watchdog configuration see the [README](https://github.com/openfaas/faas/tree/master/watchdog).
-
-For the gateway set the following environmental variables:
-
-* read_timeout, write_timeout - the default for both is "8" - seconds.
-
 ## Watchdog
 
 ### Debug your function without deploying it