Update policy_templates.json 'list' doc

Using type 'list' seems like a good idea if the policy is indeed
a list. However, it is not a good idea if it is a list of objects,
and so will need to be parsed as JSON - in that case, 'dict' is a
better fit. Added some documentation explaining why.

Bug: 872765
Change-Id: I5185f515d7bc82048bfb1eaab5d6d9ae61848eea
Reviewed-on: https://chromium-review.googlesource.com/1169469Reviewed-by: Lutz Justen <ljusten@chromium.org>
Commit-Queue: A Olsen <olsen@chromium.org>
Cr-Commit-Position: refs/heads/master@{#582214}

components/policy/resources/policy_templates.json

@@ -29,11 +29,24 @@
 #   'string-enum-list' - the user can select a set of string values from a
 #     collection of items
 #   'main' - a boolean value
-#   'list' - a list of string values
-#   'dict' - a dictionary value, containing other values indexed by strings
+#   'list' - a list of string values. Using this for a list of JSON strings
+#     is now discouraged, because the 'dict' is better for JSON.
+#   'dict' - perhaps should be named JSON. An arbitrarily complex object or
+#     array, nested objects/arrays, etc. The user defines the value with JSON.
 #   'external' - a policy that references external data.
 #     NOTE: This type is currently supported on Chrome OS only.
 #
+# NOTE to 'dict' vs 'list' - in the past, 'list' has been used for a policy
+# that is an array of objects. The user supplied a list of strings, and each
+# of those strings was parsed as JSON, resulting in an array of objects.
+# However, there are a couple of reasons why 'dict' is better for these sorts
+# of policies. Some interfaces (eg the GPO editor) only allow each list item
+# to be a single-line string, which is not great for inputting a complex JSON
+# object. It also means any example values shown in the documentation will
+# have a hybrid syntax, with both commas and new-lines being used to delimit
+# array elements - and these examples will be harder to copy and paste.
+# To conclude, prefer 'dict' to 'list' if JSON is involved.
+#
 # Each policy is tagged with risk tags that indicate potential privacy or
 # security risks. They are defined at the beginning of this file (tag
 # 'risk_tag_definitions').