Update documentation

docs/js-usage.md

@@ -419,6 +419,8 @@ An union represents a logical OR relationship. You can apply this concept to you
 
 The schema function `union` creates an OR relationship between any number of schemas that you pass as the first argument in the form of an array. On validation, the schema returns the result of the first schema that was successfully validated.
 
+> 🧠 Schemas are not guaranteed to be validated in the order they are passed to `S.union`. They are grouped by the input data type to optimise performance and improve error message. Schemas with unknown data typed validated the last.
+
 ```ts
 // TypeScript type for reference:
 // type Union = string | number;
@@ -429,8 +431,6 @@ stringOrNumberSchema.parseOrThrow("foo"); // passes
 stringOrNumberSchema.parseOrThrow(14); // passes
 ```
 
-If a bad input can be uniquely assigned to one of the schemas based on the data type, the result of that schema is returned. Otherwise, a general issue is returned that contains the issues of each schema as subissues.
-
 ### Discriminated unions
 
 ```typescript

docs/rescript-usage.md

@@ -704,6 +704,12 @@ Circle({radius: 1})->S.serializeWith(schema)
 
 `array<S.t<'value>> => S.t<'value>`
 
+An union represents a logical OR relationship. You can apply this concept to your schemas with `S.union`. This is the best API to use for variants and polymorphic variants.
+
+On validation, the `S.union` schema returns the result of the first item that was successfully validated.
+
+> 🧠 Schemas are not guaranteed to be validated in the order they are passed to `S.union`. They are grouped by the input data type to optimise performance and improve error message. Schemas with unknown data typed validated the last.
+
 ```rescript
 // TypeScript type for reference:
 // type Shape =
@@ -751,8 +757,6 @@ Square({x: 2.})->S.serializeWith(shapeSchema)
 // })
 ```
 
-The `union` will test the input against each of the schemas in order and return the first value that validates successfully.
-
 #### Enums
 
 Also, you can describe enums using `S.union` together with `S.literal`.