Add info about when you add a subfeature

docs/data-guidelines/api.md

@@ -2,6 +2,44 @@
 
 This file contains guidelines that are specific to the web API features (`api/`).
 
+
+## 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.
+
 ## Constants
 
 Don't include data for constants in BCD. The rationale for not including them is that they're not known to be a source of any compatibility issues.