diff --git a/docs/src/main/asciidoc/spring-cloud-netflix.adoc b/docs/src/main/asciidoc/spring-cloud-netflix.adoc
index 648b4084..d6c169a1 100644
--- a/docs/src/main/asciidoc/spring-cloud-netflix.adoc
+++ b/docs/src/main/asciidoc/spring-cloud-netflix.adoc
@@ -1242,6 +1242,23 @@ span all services and supersede any other route specification.
 This means that all calls such as "/myusers/101" will be forwarded to "/101" on the "users" service.
 But calls including "/admin/" will not resolve.
 
+WARNING: If you need your routes to have their order preserved you need to use a YAML
+file as the ordering will be lost using a properties file. For example:
+
+.application.yml
+[source,yaml]
+----
+ zuul:
+  routes:
+    users:
+      path: /myusers/**
+    legacy:
+      path: /**
+----
+
+If you were to use a properties file, the `legacy` path may end up in front of the `users`
+path rendering the `users` path unreachable.
+
 === Cookies and Sensitive Headers
 
 It's OK to share headers between services in the same system, but you