Add initial description guidelines (web-platform-dx#789)

Author: ddbeck

docs/README.md

@@ -64,3 +64,111 @@ The identifier should match the name, with these additional guidelines:
   - 👎 Not recommended: `fullscreen-api`
   - 👍 Recommended: `user-pseudos`
   - 👎 Not recommended: `user-valid-and-user-invalid`
+
+### Descriptions
+
+* Describe, in the active voice, what a feature does or is.
+  Think about how developers will use it, not abstract technology relationships.
+  Start with a template like this:
+
+  - `The <property> <sets> the <noun>.`
+  - `The <interface> <verbs> the <noun>.`
+  - `The <type> represents <nouns>.`
+  - `<format> is a <kind> or <variety>`.
+
+* Description text must stand alone.
+  It should not refer to text, images, or other content outside the short description.
+  Try reading the sentence aloud.
+  Does it still make sense without mentioning the name or ID?
+
+* Start descriptions with words that are distinct to the feature.
+  For example, prefer "The `some-prop` CSS property…" and avoid "The CSS property `some-prop`…."
+
+* Avoid circular descriptions.
+  For example, prefer "The `filter()` method returns the items…" over "The `filter()` method filters the items…."
+
+* It's OK to use the second person ("you", "your", and "yours") to refer to the audience when needed.
+  For example, "The interface allows you to…."
+  ([#738](https://github.com/web-platform-dx/web-features/pull/742))
+
+* Never mention support or standards status.
+  This information *will* go out of date and sooner than you think.
+
+* For every rule, there's a counterexample.
+  Use your best judgement before writing something absurd.
+
+* See the [word and phrase list](#word-and-phrase-list) for specific guidelines.
+
+#### Word and phrase list
+
+##### allows
+
+OK in usage such as "allows you to…."
+Avoid where there is no named actor, as in "the feature allows magic to happen."
+([#738](https://github.com/web-platform-dx/web-features/pull/738#discussion_r1537760761))
+
+You can often omit it with gerunds.
+For example, prefer "The widget sends…" over "The widget allows sending…."
+
+##### also known as
+
+Use this phrase to call attention to other names this feature has gone by.
+Use it at the start of a sentence at the end of the description.
+For example:
+
+ > The `some-property` CSS property sets the … value. Also known as `<alias>`.
+([#628](https://github.com/web-platform-dx/web-features/pull/628/files/a9898862cb631c83ea16f1233b3c5c4353bf7a52#r1516293423))
+
+##### defines
+
+Avoid.
+See [sets](#sets).
+([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635491))
+
+##### determines
+
+Avoid.
+See [sets](#sets).
+([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635491))
+
+##### elements
+
+Avoid "element" in reference to things that are not HTML elements.
+For example, an array of objects has "items", not "elements."
+([#750](https://github.com/web-platform-dx/web-features/pull/750#discussion_r1543011420))
+
+##### enables
+
+Avoid, except in the sense of to turn on or activate.
+See [allows](#allows).
+([#750](https://github.com/web-platform-dx/web-features/pull/750#discussion_r1547382081))
+
+##### for example
+
+Don't use it as a coordinating conjunction; start a new sentence instead.
+For example, this is an example.
+([#738](https://github.com/web-platform-dx/web-features/pull/738#discussion_r1537762579), [#742](https://github.com/web-platform-dx/web-features/pull/742))
+
+##### is used to
+
+Omit "is used" where there's no loss in meaning.
+For example, prefer "The feature reads…" over "The feature is used to read…"
+([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635981))
+
+##### provides
+
+Avoid, especially with gerunds.
+For example, prefer the "The feature writes to…" over "The feature provides writing to…."
+([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635491))
+
+##### sets
+
+Prefer this over multisyllabic alternatives, such as "defines", "determines", or "specifies".
+Use "The property sets…" but never "The property defines…."
+([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635491))
+
+##### specifies
+
+Avoid.
+See [sets](#sets).
+([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635491))