diff --git a/doc/docs.md b/doc/docs.md
index 0b382b9f07..b5839807cf 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -1272,6 +1272,8 @@ val2 := arr[333]?
 println(val2)
 ```
 
+Maps are ordered by insertion, like dictionaries in Python. The order is a guaranteed language feature. This may change in the future.
+
 ## Module imports
 
 For information about creating a module, see [Modules](#modules).