Change recommendation for multiple value parameters

Author: runejuhl

docs/index.md

@@ -178,10 +178,15 @@ There are a few things that can be checked if you review a pull request against
 * Does it need additional tests? Add the `needs-tests` label
 * Does it have failing tests? Add the `tests-fail` label
 * Are new parameters introduced? They must have datatypes
-* If you can supply one or multiple values for an attribute it's common practice
-  to enforce the datatype for one value and an array of that datatype. An
-  example for string is `Variant[String[1],Array[String[1]]]`. This can be used
-  in the Puppet code as `[$var].flatten()`
+* If you can supply multiple values for an attribute it's common practice to
+  enforce the datatype as an array of values, even if the default is a single
+  item. This cuts down on code and remove some edge cases. An example for string
+  is `Array[String[1]]` instead of `Variant[String[1],Array[String[1]]]`.
+
+  Note that previously the recommendation was to have a `Variant` type, but this
+  causes problems with values that contain Arrays, e.g. `Variant[Tuple[String,
+  Array], Array[Tuple[String, Array]]]` (which would unintentionally flatten the
+  array inside the tuple).
 * Are facts used? They should only be accessed via `$facts[]` or
   [fact()](https://github.com/puppetlabs/puppetlabs-stdlib#fact) from stdlib,
   but not topscope variables