dotnet · gewarren · Sep 25, 2020 · Sep 25, 2020 · Sep 25, 2020 · Sep 25, 2020
diff --git a/docs/fundamentals/code-analysis/code-quality-rule-options.md b/docs/fundamentals/code-analysis/code-quality-rule-options.md
@@ -9,15 +9,45 @@ no-loc: ["EditorConfig"]
 
 The *code quality* rules have additional configuration options, besides just [configuring their severity](configuration-options.md#severity-level). For example, each code quality analyzer can be configured to only apply to specific parts of your codebase. You specify these options by adding key-value pairs to the same [EditorConfig](https://editorconfig.org) file where you specify rule severities and general editor preferences.
 
-This article lists some of the available options. To see the full list of available options, see [Analyzer configuration](https://github.com/dotnet/roslyn-analyzers/blob/master/docs/Analyzer%20Configuration.md).
+## Option scopes
 
-## api_surface
+Each refining option can be configured for all rules, for a category of rules (for example, Security or Design), or for a specific rule.
+
+### All rules
+
+The syntax for configuring an option for *all* rules is as follows:
+
+|Syntax|Example|
+|-|-|
+| dotnet_code_quality.OptionName = OptionValue | `dotnet_code_quality.api_surface = public` |
+
+### Category of rules
+
+The syntax for configuring an option for a *category* of rules (such as Naming, Design, or Performance) is as follows:
+
+|Syntax|Example|
+|-|-|
+| dotnet_code_quality.RuleCategory.OptionName = OptionValue | `dotnet_code_quality.Naming.api_surface = public` |
+
+### Specific rule
+
+The syntax for configuring an option for a *specific* rule is as follows:
+
+|Syntax|Example|
+|-|-|
+| dotnet_code_quality.RuleId.OptionName = OptionValue | `dotnet_code_quality.CA1040.api_surface = public` |
+
+## Options
+
+This section lists some of the available options. To see the full list of available options, see [Analyzer configuration](https://github.com/dotnet/roslyn-analyzers/blob/master/docs/Analyzer%20Configuration.md).
+
+### api_surface
 
 | Description | Allowable values | Default value | Configurable rules |
 | - | - | - | - |
 | Which part of the API surface to analyze | `public`<br/>`internal` or `friend`<br/>`private`<br/>`all`<br/><br/>Separate multiple values with a comma (,) | `public` | [CA1000](rules/ca1000.md) [CA1003](rules/ca1003.md) [CA1008](rules/ca1008.md) [CA1010](rules/ca1010.md)<br/>[CA1012](rules/ca1012.md) [CA1024](rules/ca1024.md) [CA1027](rules/ca1027.md) [CA1028](rules/ca1028.md)<br/>[CA1030](rules/ca1030.md) [CA1036](rules/ca1036.md) [CA1040](rules/ca1040.md) [CA1041](rules/ca1041.md)<br/>[CA1043](rules/ca1043.md) [CA1044](rules/ca1044.md) [CA1051](rules/ca1051.md) [CA1052](rules/ca1052.md)<br/>[CA1054](rules/ca1054.md) [CA1055](rules/ca1055.md) [CA1056](rules/ca1056.md) [CA1058](rules/ca1058.md)<br/>[CA1063](rules/ca1063.md) [CA1708](rules/ca1708.md) [CA1710](rules/ca1710.md) [CA1711](rules/ca1711.md)<br/>[CA1714](rules/ca1714.md) [CA1715](rules/ca1715.md) [CA1716](rules/ca1716.md) [CA1717](rules/ca1717.md)<br/>[CA1720](rules/ca1720.md) [CA1721](rules/ca1721.md) [CA1725](rules/ca1725.md) [CA1801](rules/ca1801.md)<br/>[CA1802](rules/ca1802.md) [CA1815](rules/ca1815.md) [CA1819](rules/ca1819.md) [CA2217](rules/ca2217.md)<br/>[CA2225](rules/ca2225.md) [CA2226](rules/ca2226.md) [CA2231](rules/ca2231.md) [CA2234](rules/ca2234.md)<br/>|
 
-## exclude_async_void_methods
+### exclude_async_void_methods
 
 | Description | Allowable values | Default value | Configurable rules |
 | - | - | - | - |
@@ -26,7 +56,7 @@ This article lists some of the available options. To see the full list of availa
 > [!NOTE]
 > This option was named `skip_async_void_methods` in an earlier version.
 
-## exclude_single_letter_type_parameters
+### exclude_single_letter_type_parameters
 
 | Description | Allowable values | Default value | Configurable rules |
 | - | - | - | - |
@@ -35,13 +65,13 @@ This article lists some of the available options. To see the full list of availa
 > [!NOTE]
 > This option was named `allow_single_letter_type_parameters` in an earlier version.
 
-## output_kind
+### output_kind
 
 | Description | Allowable values | Default value | Configurable rules |
 | - | - | - | - |
 | Specifies that code in a project that generates this type of assembly should be analyzed | One or more fields of the <xref:Microsoft.CodeAnalysis.OutputKind> enumeration<br/><br/>Separate multiple values with a comma (,) | All output kinds | [CA2007](rules/ca2007.md) |
 
-## required_modifiers
+### required_modifiers
 
 | Description | Allowable values | Default value | Configurable rules |
 | - | - | - | - |
@@ -60,37 +90,37 @@ This article lists some of the available options. To see the full list of availa
 | `extern` | Must be declared as `extern` |
 | `async` | Must be declared as `async` |
 
-## exclude_extension_method_this_parameter
+### exclude_extension_method_this_parameter
 
 | Description | Allowable values | Default value | Configurable rules |
 | - | - | - | - |
 | Whether to skip analysis for the `this` parameter of extension methods | `true`<br/>`false` | `false` | [CA1062](rules/ca1062.md) |
 
-## null_check_validation_methods
+### null_check_validation_methods
 
 | Description | Allowable values | Default value | Configurable rules |
 | - | - | - | - |
 | Names of null-check validation methods that validate that arguments passed to the method are non-null | Allowed method name formats (separated by `|`):<br/> - Method name only (includes all methods with the name, regardless of the containing type or namespace)<br/> - Fully qualified names in the symbol's [documentation ID format](https://github.com/dotnet/csharplang/blob/master/spec/documentation-comments.md#id-string-format), with an optional `M:` prefix | None | [CA1062](rules/ca1062.md) |
 
-## additional_string_formatting_methods
+### additional_string_formatting_methods
 
 | Description | Allowable values | Default value | Configurable rules |
 | - | - | - | - |
 | Names of additional string formatting methods | Allowed method name formats (separated by `|`):<br/> - Method name only (includes all methods with the name, regardless of the containing type or namespace)<br/> - Fully qualified names in the symbol's [documentation ID format](/dotnet/csharp/language-reference/language-specification/documentation-comments#id-string-format), with an optional `M:` prefix | None | [CA2241](rules/ca2241.md) |
 
-## excluded_type_names_with_derived_types
+### excluded_type_names_with_derived_types
 
 | Description | Allowable values | Default value | Configurable rules |
 | - | - | - | - |
 | Names of types, such that the type and all its derived types are excluded for analysis | Allowed symbol name formats (separated by `|`):<br/> - Type name only (includes all types with the name, regardless of the containing type or namespace)<br/> - Fully qualified names in the symbol's [documentation ID format](/dotnet/csharp/language-reference/language-specification/documentation-comments#id-string-format), with an optional `T:` prefix | None | [CA1303](rules/ca1303.md) |
 
-## excluded_symbol_names
+### excluded_symbol_names
 
 | Description | Allowable values | Default value | Configurable rules |
 | - | - | - | - |
 | Names of symbols that are excluded for analysis | Allowed symbol name formats (separated by `|`):<br/> - Symbol name only (includes all symbols with the name, regardless of the containing type or namespace)<br/> - Fully qualified names in the symbol's [documentation ID format](/dotnet/csharp/language-reference/language-specification/documentation-comments#id-string-format). Each symbol name requires a symbol kind prefix, such as `M:` prefix for methods, `T:` prefix for types, and `N:` prefix for namespaces.<br/> - `.ctor` for constructors and `.cctor` for static constructors | None | [CA1062](rules/ca1062.md) [CA1303](rules/ca1303.md) [CA2000](rules/ca2000.md) [CA2100](rules/ca2100.md) [CA2301](rules/ca2301.md) [CA2302](rules/ca2302.md)<br/>[CA2311](rules/ca2311.md) [CA2312](rules/ca2312.md) [CA2321](rules/ca2321.md) [CA2322](rules/ca2322.md) [CA2327](rules/ca2327.md) [CA2328](rules/ca2328.md)<br/>[CA2329](rules/ca2329.md) [CA2330](rules/ca2330.md) [CA3001](rules/ca3001.md) [CA3002](rules/ca3002.md) [CA3003](rules/ca3003.md) [CA3004](rules/ca3004.md)<br/>[CA3005](rules/ca3005.md) [CA3006](rules/ca3006.md) [CA3007](rules/ca3007.md) [CA3008](rules/ca3008.md) [CA3009](rules/ca3009.md) [CA3010](rules/ca3010.md)<br/>[CA3011](rules/ca3011.md) [CA3012](rules/ca3012.md) [CA5361](rules/ca5361.md) CA5376 CA5377 [CA5378](rules/ca5378.md)<br/>[CA5380](rules/ca5380.md) [CA5381](rules/ca5381.md) CA5382 CA5383 CA5384 CA5387<br/>CA5388 [CA5389](rules/ca5389.md) CA5390 |
 
-## disallowed_symbol_names
+### disallowed_symbol_names
 
 | Description | Allowable values | Default value | Configurable rules |
 | - | - | - | - |

diff --git a/docs/fundamentals/code-analysis/configuration-options.md b/docs/fundamentals/code-analysis/configuration-options.md
@@ -7,7 +7,19 @@ no-loc: ["EditorConfig"]
 ---
 # Configuration options for code analysis
 
-Code analysis code analysis rules have various configuration options. The most common option you'll configure is a rule's severity. You can configure severity level for both [code quality rules](rules/quality-rules-reference.md) and [code style rules](/visualstudio/ide/editorconfig-language-conventions). Code quality rules have additional configuration options, such as which method names the rule should apply to, or whether only the public API surface should be analyzed.
+Code analysis rules have various configuration options. These options are specified as key-value pairs in a configuration file. For example,
+
+```ini
+<option key> = <option value>
+```
+
+The most common option you'll configure is a rule's severity. You can configure severity level for all analyzer rules, including [code quality rules](rules/quality-rules-reference.md) and [code style rules](/visualstudio/ide/editorconfig-language-conventions).
+
+You can also configure additional options to customize rule behavior:
+
+- Code quality rules have [additional options](code-quality-rule-options.md) to configure behavior, such as which method names a rule should apply to.
+- Code style rules have [custom code style options](/visualstudio/ide/editorconfig-code-style-settings-reference).
+- Third party analyzer rules can define their own configuration options, with custom key names and value formats.
 
 You specify configuration options in an [EditorConfig file](/visualstudio/ide/create-portable-custom-editor-options). You can apply EditorConfig file conventions to a folder, a project, or an entire repo by placing the file in the corresponding directory. If you have an existing *.editorconfig* file for editor settings such as indent size or whether to trim trailing whitespace, you can place your code analysis configuration options in the same file. Add an entry for each rule you want to configure, and place it under the corresponding file extension section, for example, `[*.cs]`.
 
@@ -51,24 +63,44 @@ Rule-specific options can be applied to a single rule, a set of rules, or all ru
 - [Rule severity level](#severity-level)
 - [Options specific to *code-quality* rules](code-quality-rule-options.md)
 
-To set one of these options for a single rule, use the following syntax.
+### Severity level
+
+The following table shows the different rule severities that you can configure for all analyzer rules, including [code quality](rules/quality-rules-reference.md) and [code style](/visualstudio/ide/editorconfig-language-conventions) rules.
+
+| Severity | Build-time behavior |
+|-|-|
+| `error` | Violations appear as build *errors* and cause builds to fail.|
+| `warning` | Violations appear as build *warnings* but do not cause builds to fail (unless you have an option set to treat warnings as errors). |
+| `suggestion` | Violations appear as build *messages* and as suggestions in the Visual Studio IDE. |
+| `silent` | Violations aren't visible to the user. |
+| `none` | Rule is suppressed completely. |
+| `default` | The default severity of the rule is used. |
+
+> [!TIP]
+> For information about how rule severities surface in Visual Studio, see [Severity levels](/visualstudio/ide/editorconfig-language-conventions#severity-levels).
+
+#### Scope
+
+To set the rule severity for a single rule, use the following syntax.
 
 ```ini
-dotnet_diagnostic.<rule ID>.<option name> = <option value>
+dotnet_diagnostic.<rule ID>.severity = <severity value>
 ```
 
-To set one of these options for a category of analyzer rules, use the following syntax.
+To set the default rule severity for a category of analyzer rules, use the following syntax.
 
 ```ini
-dotnet_analyzer_diagnostic.category-<rule category>.<option name> = <option value>
+dotnet_analyzer_diagnostic.category-<rule category>.severity = <severity value>
 ```
 
-To set one of these options for all analyzer rules, use the following syntax.
+To set the default rule severity for all analyzer rules, use the following syntax.
 
 ```ini
-dotnet_analyzer_diagnostic.<option name> = <option value>
+dotnet_analyzer_diagnostic.severity = <severity value>
 ```
 
+#### Precedence
+
 If you have multiple entries that can be applied to the same rule ID, precedence is chosen in the following order:
 
 - An entry for an individual rule by ID takes precedence over an entry for a category.
@@ -84,19 +116,3 @@ dotnet_analyzer_diagnostic.severity = suggestion
 ```
 
 In the preceding example, all three severity entries are applicable to CA1822. However, using the specified precedence rules, the first rule ID-based entry wins over the next entries. In this example, CA1822 will have an effective severity of `error`. All other rules within the "Performance" category will have a severity of `warning`.
-
-### Severity level
-
-The following table shows the different rule severities that you can configure for both [code quality](rules/quality-rules-reference.md) and [code style](/visualstudio/ide/editorconfig-language-conventions) rules.
-
-| Severity | Build-time behavior |
-|-|-|
-| `error` | Violations appear as build *errors* and cause builds to fail.|
-| `warning` | Violations appear as build *warnings* but do not cause builds to fail (unless you have an option set to treat warnings as errors). |
-| `suggestion` | Violations appear as build *messages* and as suggestions in the Visual Studio IDE. |
-| `silent` | Violations aren't visible to the user. |
-| `none` | Rule is suppressed completely. |
-| `default` | The default severity of the rule is used. |
-
-> [!TIP]
-> For information about how rule severities surface in Visual Studio, see [Severity levels](/visualstudio/ide/editorconfig-language-conventions#severity-levels).