diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index afa3ed83a1b..e3244264bf4 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -32,6 +32,31 @@ For example, the `fetch()` API is a feature, the `:has()` CSS pseudo-class funct For the time being, this repository focuses only on features that are implemented in some browser and that are already documented on MDN. +### Hints for distinguishing features + +Sometimes it can be hard to tell whether something (like an HTML attribute or JavaScript method) is a distinct feature or part of another feature. +Here are some questions to ask yourself when deciding whether something is a distinct feature of the web platform: + +- Is there evidence that developers recognize it as a feature? + Blog posts, Stack Overflow questions, and social media posts by developers about the feature are good places to learn whether developers see something as part of a category or as standing alone + (they're also a good source of other information, such as a name for the feature). + +- Do existing publications already describe this as a distinct feature? + For example, an original Can I Use entry (or request for one on [Fyrd/caniuse](https://github.com/Fyrd/caniuse/issues)) is a good sign that developers will recognize this as a feature. + Articles in developer-audience publications (such as CSS-Tricks, DEV.to, and sometimes MDN) are also helpful indicators. + +- Do you _expect_ developers to recognize it as a feature? + Very new features are harder to sort out because developers don't know about them already. + In such cases, you have to make educated guesses. + Sometimes you can use prior features' development and specification process to make good guesses. + For example, TC39 proposals often emerge as distinct features, while CSS specifications often contain several distinct but related features or incremental additions to existing features. + Sometimes you may need to talk to developers or subject matter experts before making a decision. + +Creating features is more art than science. +You won't always get it right. +That's OK! +Features can be renamed, split, or merged later. + ### Feature file name and format Features in this repository are authored as **YAML files** that are stored in the [`features`](../features) directory. Each file corresponds to a single feature, and contains metadata about the feature, such as its name, description, specification, or support data.