MTA-6826, 6827, 6828, 6829, 6830, 6831 CQA April work for rules development guide

assemblies/rules-development-guide/assembly_creating-rule.adoc

@@ -16,11 +16,7 @@ endif::[]
 :context: creating-rule
 
 [role="_abstract"]
-You can refer to example rules that describe how to create a YAML rule. This assumes that you already have MTA installed. See the MTA CLI Guide for installation instructions.
-
-//This section describes how to create a {ProductShortName} YAML rule. This assumes that you already have {ProductShortName} installed. See the {ProductShortName} {ProductDocUserGuideURL}[_{UserCLIBookName}_] for installation instructions.//
-
-include::topics/rules-development/create-basic-yaml-rule-template.adoc[leveloffset=+1]
+To analyze applications in `Python`, `Node.js`, `Go`, and `C#`, the Architect must create a custom rule. A custom rule includes conditions and patterns that describe an issue. You must resolve issues when refactoring applications before migrating them to a target platform. 
 
 include::topics/rules-development/create-first-yaml-rule.adoc[leveloffset=+1]
 

assemblies/rules-development-guide/assembly_java-conditions-detailed.adoc

@@ -1,10 +1,8 @@
 :_newdoc-version: 2.18.3
 :_template-generated: 2025-05-28
-
-ifdef::context[:parent-context-of-java-conditions-capabilities: {context}]
-
 :_mod-docs-content-type: ASSEMBLY
 
+ifdef::context[:parent-context-of-java-conditions-capabilities: {context}]
 ifndef::context[]
 [id="java-conditions-capabilities"]
 endif::[]
@@ -16,13 +14,8 @@ endif::[]
 :context: java-conditions-capabilities
 
 [role="_abstract"]
-The `java.referenced` capability in the when condition for Java rules can define search queries for the following fields in the source code:
-
-* Locations - such as the classes, methods, packages and so on
-* Annotations
-* Patterns
+As an Architect, you can create custom rules to analyze the `Java` source code for problematic patterns before migration. The `Java` provider uses Eclipse Java Development Tools Language Server (JDTLS) that depends on the  Eclipse Java Development Toolkit for utilities to search the source code.
 
-You can refer to this section for a detailed explanation on the Locations, Annotations, and Patterns.
 
 include::topics/rules-development/yaml-java-locations.adoc[leveloffset=+1]
 

assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adoc

@@ -16,12 +16,9 @@ endif::[]
 :context: logical-chaining-custom-variables
 
 [role="_abstract"]
-You can create complex conditions in rules by using the following:
+When you create a rule, you can limit the search query in the source code by using logical conditions, condition chaining, nested conditions, and custom variables. You can narrow the search to specific files, a pattern, or a combination of conditions.
 
-* Logical conditions inform the provider how to handle more than one condition in a when block. The analyzer provides the logical conditions, `and` and `or`, that you can use to aggregate results of other conditions.
-* Condition chaining uses the output of one condition as the input in another condition of the when block. Assign the output to a variable in one condition and reuse it in other conditions in the when block.
-* Nested conditions to create conditions that depend on the evaluation of other conditions.
-* Custom variables to capture specific information from the code that is evaluated by a rule. You can use the custom variable in the message displayed for the code if it contains a violation defined by the rule.
+include::topics/rules-development/yaml-rule-condition-complexity.adoc[leveloffset=+1]
 
 include::topics/rules-development/yaml-and-condition.adoc[leveloffset=+1]
 

assemblies/rules-development-guide/assembly_rule-rulesets.adoc

@@ -18,10 +18,7 @@ endif::[]
 [role="_abstract"]
 A set of rules forms a ruleset. {ProductShortName} does not require every rule file to belong to a ruleset, but you can use rulesets to group multiple rules that achieve a common goal and to pass the rules to the rules engine.
 
-To use multiple rule files, you can either:
-
-* Place the rule files in a directory and add a ruleset.yaml file. {ProductShortName} treats the directory as a ruleset, and you can pass the directory path as input to the `--rules` option.
-* Specify multiple rules files by using the `--rules` option when you run an analysis.
+The `ruleset.yaml` file stores the metadata of the ruleset. You can group multiple similar custom rules and create a ruleset for them.
 
 include::topics/rules-development/yaml-rulesets.adoc[leveloffset=+1]
 

assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc

@@ -21,9 +21,9 @@ You can use rule actions to generate information about the source code. The rule
 Rules can include the following types of actions:
 
 * `Message`: use message action to display an informative message in the static report that contains the violation triggered by the rule.
-* `Tag`: use tags to categorize parts of the source code. For example, Backend=Java, where Backend is the key and Java is the value.
+* `Tag`: use tags to categorize parts of the source code. For example, `Backend=Java`, where `Backend` is the key and `Java` is the value.
 
-Each rule includes either one of them or both of them. 
+Each rule includes either one action tag or both. 
 
 include::topics/rules-development/yaml-tag-actions.adoc[leveloffset=+1]
 

assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc

@@ -16,21 +16,9 @@ endif::[]
 :context: rules-prov-cond
 
 [role="_abstract"]
-The providers are the modular components in charge of analyzing a given language. The external providers, except `C#`, are able to analyze code by leveraging the Language Server Protocol (LSP). Through the LSP, all code analysis is abstracted away from the analysis engine and left to the specific LSP server to run the search query defined in the rule on the source code. 
+Providers are the modular components that work with the analysis engine and the Language Server Protocol (LSP) server to analyze the application source code. They run search queries on the source code based on rule patterns to scan for issues. 
 
-Additionally, {ProductShortName} provides a built-in provider with abilities such as XML parsing, running regular expressions on files, and so on.
-
-Currently, {ProductShortName} supports the following providers:
-
-* builtin
-* Java 
-* C#
-* External providers (for `Python`, `Go`, and `Node.js` applications) initialized by the generic provider binary
-
-[NOTE]
-====
-You can use the generic provider binary to create an external provider for any language that is compliant with link:https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/[LSP 3.17 specifications].
-====
+include::topics/rules-development/con_external_providers.adoc[leveloffset=+1]
 
 include::topics/rules-development/con_provider-capability-in-custom-rules.adoc[leveloffset=+1]
 

assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc

@@ -16,13 +16,7 @@ endif::[]
 :context: rule-yaml-metadata
 
 [role="_abstract"]
-The rule metadata contains information about the migration defined by the Architect. You can use rule metadata to:
-
-* Estimate the total migration effort. 
-* Prioritize issues that must be resolved based on the effort.
-* Evaluate if a resolution is mandatory through rule category before migrating the applications to the target technologies or platforms.
-* Define labels used by {ProductShortName} to filter rules for an analysis.
-
+As an Architect, you include information about effort in the rule metadata. Effort is a numerical value that accounts for the complexity in resolving the issue described in the rule. In the metadata, you can add category and label that guides Migrators when they resolve issues in the code. 
 
 include::topics/rules-development/yaml-rule-metadata.adoc[leveloffset=+1]
 

assemblies/rules-development-guide/assembly_rules-introduction.adoc

@@ -16,13 +16,13 @@ endif::[]
 :context: rules-introduction
 
 [role="_abstract"]
-This guide is intended for software engineers who want to create custom YAML-based rules for {ProductName} ({ProductShortName}) tools.
+As an Architect, see the following sections to understand rules and rule syntax so that, you can create custom YAML-based rules for {ProductName} ({ProductShortName}) tools.
 
 include::topics/rules-development/about-rules.adoc[leveloffset=+1]
 
 include::topics/rules-development/yaml-rule-structure-syntax.adoc[leveloffset=+1]
 
-ifdef::parent-context-of-getting-started[:context: {parent-context-of-rules-introduction}]
-ifndef::parent-context-of-getting-started[:!context:]
+ifdef::parent-context-of-rules-introduction[:context: {parent-context-of-rules-introduction}]
+ifndef::parent-context-of-rules-introduction[:!context:]
 
 :!rules-introduction:

docs/rules-development-guide/master.adoc

@@ -11,27 +11,18 @@ include::topics/templates/document-attributes.adoc[]
 [id="rules-development-guide"]
 = Configuring and using rules for an {ProductShortName} analysis
 
-
 //Inclusive language statement
 include::topics/making-open-source-more-inclusive.adoc[]
 
 include::assemblies/rules-development-guide/assembly_rules-introduction.adoc[leveloffset=+1]
-
 include::assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc[leveloffset=+1]
-
 include::assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc[leveloffset=+1]
-
 include::assemblies/rules-development-guide/assembly_java-conditions-detailed.adoc[leveloffset=+1]
-
 include::assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adoc[leveloffset=+1]
-
 include::assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc[leveloffset=+1]
-
 include::assemblies/rules-development-guide/assembly_creating-rule.adoc[leveloffset=+1]
-
 include::assemblies/rules-development-guide/assembly_rule-rulesets.adoc[leveloffset=+1]
 
-
 [id="_additional-resources"]
 == Additional resources
 

docs/topics/rules-development/about-rules.adoc

@@ -8,29 +8,27 @@
 = The {ProductShortName} rules
 
 [role="_abstract"]
-The {ProductFullName} contains the analyzer that uses pluggable providers and rules to analyze static code, dependencies, and other files in your application. 
+{ProductFullName} analyzes the application source code to find issues based on user-generated rule and default rule definitions. You can fix issues in an analysis report before migrating the code to a target platform. You can view the rule syntax information to create a new rule or a ruleset.
 
-The analyzer works with providers to detect issues that cause problems when you migrate the application to target technologies. The rule definition contains metadata description and condition patterns that describe a violation.
+A ruleset is a collection of one or more rules. An Architect can create rulesets to organize one or more rules that analyze the source code for a specific target platform.
 
-The analyzer runs a search query on the source code to match the violation described in the rule definition. The rule definition also contains a message that MTA displays when triggering an issue because of the violation. The analyzer uses default and user-provided (custom) rules during an analysis to identify issues. 
+You can use rules or rulesets as input arguments in an analysis. You can perform a rule-based analysis in the {ProductShortName} CLI, user interface, or by using one of the IDE plugins for {ProductShortName} (Visual Studio Code or IntelliJ).
 
-[NOTE]
-====
-An {ProductShortName} Architect can create custom rules. You can use custom rules to identify the use of custom libraries or other components in the source code that might not be covered by the standard migration rules.
-====
+{mta-dl-plugin} uses rules to generate AI-assisted code resolutions. {mta-dl-plugin} uses the issue description and metadata in rules to form well-defined contexts. These contexts generate AI-assisted suggestions to resolve issues in the code that {ProductShortName} identified through an analysis.
 
-A collection of one or more rules is called a ruleset. Creating rulesets provides a way of organizing multiple rules that analyze the source code for a specific target platform.
+== How {ProductShortName} performs an analysis
 
-You can use rules or rulesets as input arguments in an analysis. You can perform a rule-based analysis in the {ProductShortName} CLI, user interface, or by using one of the IDE plugins for {ProductShortName} (Visual Studio Code or IntelliJ).
+{ProductFirstRef} contains the analyzer that uses pluggable providers and rules to analyze static code, dependencies, and other files in your application. 
 
-The rules can be used by {mta-dl-plugin} to generate AI-assisted code resolutions. The issue description and metadata in rules are used by the {mta-dl-plugin} to form well-defined contexts. These contexts generate AI-assisted suggestions to resolve issues in the code that are identified through an analysis.
+The analyzer works with providers to detect issues that cause problems when you migrate the application to target technologies. The rule definition contains metadata description and condition patterns that describe a violation.
+
+The analyzer runs a search query on the source code to match the violation described in the rule definition. The rule definition also contains a message that {ProductShortName} displays when triggering an issue because of the violation. The analyzer uses default and user-provided (custom) rules during an analysis to identify issues. 
 
 
 ifndef::rules-development-guide[]
 For instructions on how to write custom rules, see [_{RulesDevBookName}_].
 endif::rules-development-guide[]
 
-
 [role="_additional-resources"]
 .Additional resources
 * link:https://docs.redhat.com/en/documentation/migration_toolkit_for_applications/8.0/html/configuring_and_using_red_hat_developer_lightspeed_for_mta/index[Configuring and using Red Hat Developer Lightspeed for MTA]

docs/topics/rules-development/con_external_providers.adoc

@@ -0,0 +1,26 @@
+:_newdoc-version: 2.18.7
+:_template-generated: 2026-03-27
+:_mod-docs-content-type: CONCEPT
+
+[id="external-providers_{context}"]
+= Provider capabilities in custom rules
+
+[role="_abstract"]
+The external providers, except `C#`, use the Language Server Protocol (LSP) server to perform an analysis. The provider forms a search query and sends it to the LSP server to check against the application. When the LSP server returns a match for the search in the source code, the analyzer triggers a violation. 
+
+Currently, {ProductShortName} supports the following providers:
+
+* `builtin`
+* `Java` 
+* `C#`
+* External providers (for `Python`, `Go`, and `Node.js` applications) initialized by the generic provider binary
+
+[NOTE]
+====
+You can use the generic provider binary to create an external provider for any language that is compliant with LSP specifications.
+====
+
+.Additional resources
+
+* link:https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/[LSP 3.17 specifications]
+

docs/topics/rules-development/con_provider-capability-in-custom-rules.adoc

@@ -6,15 +6,14 @@
 = Provider capabilities in custom rules
 
 [role="_abstract"]
-In a rule, the `when` block is where the conditions for matching the rule are specified. Each provider offers a series of capabilities to do matching.
+As an Architect, you define conditions and patterns in custom rules that {ProductShortName} uses to match against the source code and dependencies in an analysis. You can specify the conditions in the `when` block of the rule. You can use capabilities available in each provider to match rule patterns.
 
-The search query in the rule condition can contain patterns, code locations, specific dependencies to be found, and so on, to evaluate the source code and dependencies. The provider sends the LSP server a request to check the search query against the application being analyzed. When the LSP server returns a match for the search in the source code, the analyzer triggers a violation.
-
-The syntax of the when block is as follows: it contains a single condition, but that condition might have multiple conditions nested beneath it.
+The `when` block contains a single condition, but that condition might have one or more conditions nested under it.
 
+[subs="+quotes"]
 ----
 when:
-  <condition>
-    <nested-condition>
+  _<condition>_
+    _<nested-condition>_
 ----
 

docs/topics/rules-development/create-csharp-custom-rule.adoc

@@ -7,14 +7,14 @@
 = Creating a custom C# rule
 
 [role="_abstract"]
-You can create custom rules to analyze `C#` applications by using the {ProductShortName} CLI, user interface, or IDE extension. The following example shows how to run a CLI analysis for a C# application.
+You can create custom rules to analyze `C#` applications by using the {ProductShortName} CLI, user interface, or IDE extension. The following example shows how to run a CLI analysis for a `C#` application.
 
 You can use a custom rule to check if {ProductShortName} triggers an incident when it detects the `WebMatrix.WebData.WebSecurity` class in a `C#` example project.
 
 .Prerequisites
 
 * You installed the `ilspycmd` and `paket` dependencies.
-* You installed the `dotnet tools` and exported the `dotnet tools` path by using the `export PATH="$PATH:<path/to/.dotnet/tools"` command.
+* You installed the `dotnet tools` and exported the `dotnet tools` path by using the `export PATH="$PATH:__<path_to_.dotnet_tools>__"` command.
 
 .Procedure
 . Create a `csharp-rule.yaml` file in your `Home` directory. 
@@ -26,18 +26,18 @@ You can use a custom rule to check if {ProductShortName} triggers an incident wh
 ----
 - category: mandatory
   customVariables: []
-  description: WebMatrix.WebData.WebSecurity is not available in .NET Core
+  description: WebMatrix.WebData.WebSecurity is not available in .NET
   effort: 8
   labels:
   - konveyor.io/source=dotnet
   - konveyor.io/target=dotnet-core
   links:
-  - title: Introduction to Identity on ASP.NET Core
+  - title: Introduction to Identity on ASP.NET Core 
     url: https://learn.microsoft.com/en-us/aspnet/core/security/authentication/identity
-  - title: Migrate Authentication and Identity to ASP.NET Core
+  - title: Migrate Authentication and Identity to ASP.NET 
     url: https://learn.microsoft.com/en-us/aspnet/core/migration/identity
   message: |
-    WebMatrix.WebData.WebSecurity is not available in .NET Core and must be replaced with ASP.NET Core Identity.
+    WebMatrix.WebData.WebSecurity is not available in .NET and must be replaced with ASP.NET Core Identity.
 
     Migration actions:
     - Add Microsoft.AspNetCore.Identity.EntityFrameworkCore NuGet package
@@ -55,23 +55,23 @@ You can use a custom rule to check if {ProductShortName} triggers an incident wh
       pattern: WebMatrix.WebData.WebSecurity
 ----
 
-. Open a C# project that has the `WebMatrix.WebData.WebSecurity` class.
+. Open a `C#` project that has the `WebMatrix.WebData.WebSecurity` class.
 
 . Run an analysis with the following command in the {ProductShortName} CLI:
 +
 
-[source, terminal]
+[source, terminal, subs="+quotes"]
 ----
-$ ./mta-cli analyze -i _path_to_C#_app_ -o _path_to_report_ --overwrite --run-local=false --enable-default-rulesets=false --mode source-only --rules ~/csharp-rule.yaml 
+$ *./mta-cli analyze -i _<path_to_C#_app>_ -o _<path_to_report>_* *--overwrite --run-local=false --enable-default-rulesets=false --mode* *source-only --rules ~/csharp-rule.yaml*
 ----
 +
 
 [NOTE]
 ====
-Add the `--overwrite` option if you want to use the same directory for the report when you run subsequent tests. {ProductShortName} overwrites the current report with the result of the latest analysis that you ran.
+Add the `--overwrite` option if you want to use the same directory for the report when you run more tests. {ProductShortName} overwrites the current report with the result of the latest analysis that you ran.
 ====
 
-. Open the static report at _path_to_report_ in your browser.
+. Open the static report at _<path_to_report>_ in your browser.
 
-. Navigate to the issues to verify the *`WebMatrix.WebData.WebSecurity` is not available in `.NET Core`* issue.
+. Navigate to the issues to verify the *`WebMatrix.WebData.WebSecurity` is not available in `.NET`* issue.