Refine docs

docs/migration-guide/to-15.md

@@ -51,16 +51,50 @@ If you want to continue using Stylelint to enforce stylistic consistency, you ca
 
 ### Added `declaration-property-value-no-unknown` rule
 
-We added the [`declaration-property-value-no-unknown`](../../lib/rules/declaration-property-value-no-unknown/README.md) rule and turned it on in our [recommended](https://www.npmjs.com/package/stylelint-config-recommended) and [standard](https://www.npmjs.com/package/stylelint-config-standard) configs.
+We added the [`declaration-property-value-no-unknown`](../../lib/rules/declaration-property-value-no-unknown/README.md) rule. It will flag property-value pairs that are unknown in the CSS specifications, for example:
 
-The rule checks for unknown property-value pairs in declarations. If you use values that aren't in the CSS specifications, you can use the rule's secondary options to make the rule more permissive. You can either:
+```css
+a {
+  top: red;
+}
+```
+
+The `top` property accepts either a `<length>`, `<percentage>` or the `auto` keyword. The rule will flag `red` as it's a `<color>`.
+
+Many of you have requested this rule, and we plan to add more like it to help you [avoid errors](../user-guide/rules.md#avoid-errors) in your CSS.
+
+To turn it on in your configuration object:
+
+```diff json
+{
+  "extends": ["stylelint-config-standard"],
+  "rules" {
++   "declaration-property-value-no-unknown": true
+    ..
+   }
+}
+```
+
+The rule uses [CSSTree](https://github.com/csstree/csstree) and its [syntax dictionary](https://csstree.github.io/docs/syntax/) of 604 properties, 386 types and 130 functions. You can help identify and plug any gaps in its dictionary by either updating [mdn-data](https://github.com/mdn/data/) or [CSSTree's patch file](https://github.com/csstree/csstree/blob/master/data/patch.json).
+
+If you use values that aren't in the CSS specifications, you can use the rule's secondary options to make the rule more permissive. You can either:
 
 - ignore properties or values outright
 - extend the properties and values syntaxes
 
-The latter is a powerful approach that ensures only specific exceptions are allowed.
+The latter ensures only specific exceptions are allowed.
+
+If you currently use the [`stylelint-csstree-validator`](https://www.npmjs.com/package/stylelint-csstree-validator) plugin, you can continue to use it alongside the new rule by limiting the plugin to check only at-rule names and preludes.
 
-We hope to add more rules like this to Stylelint that help you [avoid errors](../user-guide/rules.md#avoid-errors) in your code.
+```diff json
+{
+  "rules" {
+    "csstree/validator": [true, {
++      "ignoreProperties": ["/.+/"]
+    }]
+  }
+}
+```
 
 ## Breaking changes
 

docs/user-guide/rules.md

@@ -79,7 +79,7 @@ Disallow unknown things with these `no-unknown` rules.
 
 - [`annotation-no-unknown`](../../lib/rules/annotation-no-unknown/README.md): Disallow unknown annotations (Ⓡ & Ⓢ).
 - [`at-rule-no-unknown`](../../lib/rules/at-rule-no-unknown/README.md): Disallow unknown at-rules (Ⓡ & Ⓢ).
-- [`declaration-property-value-no-unknown`](../../lib/rules/declaration-property-value-no-unknown/README.md): Disallow unknown values for property within declarations.
+- [`declaration-property-value-no-unknown`](../../lib/rules/declaration-property-value-no-unknown/README.md): Disallow unknown values for properties within declarations.
 - [`function-no-unknown`](../../lib/rules/function-no-unknown/README.md): Disallow unknown functions (Ⓡ & Ⓢ).
 - [`media-feature-name-no-unknown`](../../lib/rules/media-feature-name-no-unknown/README.md): Disallow unknown media feature names (Ⓡ & Ⓢ).
 - [`no-unknown-animations`](../../lib/rules/no-unknown-animations/README.md): Disallow unknown animations.

lib/rules/declaration-property-value-no-unknown/README.md

@@ -1,6 +1,6 @@
 # declaration-property-value-no-unknown
 
-Disallow unknown values for property within declarations.
+Disallow unknown values for properties within declarations.
 
 <!-- prettier-ignore -->
 ```css
@@ -9,6 +9,17 @@ a { top: unknown; }
  * property and value pairs like these */
 ```
 
+This is an experimental rule with some false negatives that will be patched in minor releases.
+
+It sometimes overlaps with:
+
+- [`color-no-invalid-hex`](../color-no-invalid-hex/README.md)
+- [`function-no-unknown`](../function-no-unknown/README.md)
+- [`string-no-newline`](../string-no-newline/README.md)
+- [`unit-no-unknown`](../unit-no-unknown/README.md)
+
+If duplicate problems are flagged, you can turn off the corresponding rule.
+
 This rule considers values for properties defined within the CSS specifications to be known. You can use the `propertiesSyntax` and `typesSyntax` secondary options to extend the syntax.
 
 ## Options
@@ -17,6 +28,11 @@ This rule considers values for properties defined within the CSS specifications
 
 The following patterns are considered problems:
 
+<!-- prettier-ignore -->
+```css
+a { top: red; }
+```
+
 <!-- prettier-ignore -->
 ```css
 a { top: unknown; }
@@ -38,7 +54,7 @@ a { top: var(--foo); }
 
 ### `ignoreProperties: { "property": ["/regex/", /regex/, "non-regex"]|"/regex/"|/regex/|"non-regex" }`
 
-Ignore the specified properties. Keys in the object indicate property names. If a string in the object is surrounded with `"/"`, it is interpreted as a regular expression. For example, `"/.+/"` matches any strings.
+Ignore the specified property and value pairs. Keys in the object indicate property names. If a string in the object is surrounded with `"/"`, it's interpreted as a regular expression. For example, `"/.+/"` matches any strings.
 
 Given: