Updates to reflect the rules from vinyl

docs/data-guidelines.md

@@ -13,15 +13,43 @@ If it's helpful to understanding the rule, summarize the rationale. Definitely c
 -- END TEMPLATE -->
 
 
-## Adding subfeatures
-
-Subfeatures should be added for all methods, properties, tags, attributes, method arguments, and other specification entities, provided that they have an implementation in one or more of the supported browser engines.
-
-In addition, subfeatures should be added to indicate support for specific behaviours, such as support in workers, or that an interface is serializable.
-This ensures that every element that is actually in some browser has a statement of its compatibility, and may optionally also have an MDN documentation link and a specifation URL link. 
-
-For example, the `ImageData` interface was initially defined with `data`, `height` and `width` properties.
-The subfeatures for the `colorSpace` property, the constructor, and support for using the API in workers, were added after the first implementation of these in a browser.
+## Adding features and subfeatures
+
+A _feature_ is a top level item in the web platform. This includes (non-exhaustively): individual Web API interfaces, children of namespace object like `Intl`, HTML elements, CSS properties, CSS selectors, CSS types, CSS @rules, Javascript operators, Javascript builtins, HTTP headers, and so on.
+A json file should be created for every feature that has a released public implementation on one of the supported set of browsers (and not before).
+The top level entry in the file indicates the supported browser versions for the feature.
+
+A feature may contain _subfeatures_, which document the browser versions in which parts of the parent feature were first supported or removed.
+For example, a method subfeature entry would indicate the browser versions in which the method was added to the parent interface.
+Subfeatures are also used to reflect changes in behaviour in particular versions, such as "support in workers" or "returns a promise".
+A subfeature might nest its own subfeatures, and so on. For example, an interface feature might nest a method subfeature, which nests an option parameter, which then nests a subfeature for a value of that option.
+
+Subfeatures entries are added for all:
+
+- interface methods and properties that have an implementation in any of the supported browsers.
+- ?
+
+Otherwise, the rule is that a subfeature is only needed when there is some change in functionality or behaviour with respect to the parent feature or subfeature.
+This applies to "everything else": behaviours, method parameters, CSS attribute values, etc.
+
+> **Tip:** A good rule of thumb is that if a subfeature has the same compatibility information as its parent, then the subfeature is not needed.
+> This does not apply to interface methods and properties!
+
+Here is an example scenario:
+
+- An interface is defined in a specification with a method that has two parameters.
+- A supported browser implements the method and both the parameters:
+  - A subfeature is created for the method (by default)
+  - subfeature are not created for the method parameters because they were created in the same version as the methods; there is no compatibility change.
+- Another browser implements the methods, but only one of the parameters.
+  - A subfeature is added to the method subfeature, but only for the parameter that is _not_ supported by the second browser.
+- Yet another browser implements the method with a new parameter. 
+  - A method subfeature is added for the new parameter because it was added in a different version than the parent method.
+- The specification changes to require that the interface now can be used in workers:
+  - A subfeature is added to the interface feature because this is a change in compatibility.
+  - 
+    > **Note:** If all browsers implemented worker support in their first implementation then no subfeature would be required.
+    > It is only once a browser does something different that the subfeature is created.
 
 ## Constructors