MTA-2153: Docs improvements

docs/getting-started-guide/master.adoc

@@ -26,7 +26,7 @@ include::topics/mta-what-is-the-toolkit.adoc[leveloffset=+1]
 include::topics/new-mta-features.adoc[leveloffset=+2]
 
 // Windup Rules
-include::topics/about-rules.adoc[leveloffset=+2]
+include::topics/mta-about-rules.adoc[leveloffset=+2]
 
 == Supported configurations
 

docs/rules-development-guide/master.adoc

@@ -24,7 +24,7 @@ include::topics/rules-guide-intro.adoc[leveloffset=+2]
 include::topics/mta-about-home-var.adoc[leveloffset=+3]
 
 // MTA Rules
-include::topics/about-rules.adoc[leveloffset=+2]
+include::topics/mta-about-rules.adoc[leveloffset=+2]
 
 [id="creating-yaml-rules_{context}"]
 == Creating YAML rules
@@ -81,21 +81,21 @@ include::topics/rule-categories.adoc[leveloffset=+1]
 // Rule Story Points
 include::topics/about-story-points.adoc[leveloffset=+2]
 
-For more information on categorizing tasks, see xref:rule-categories_{context}[Using custom rule categories].
+// For more information on categorizing tasks, see xref:rule-categories_{context}[Using custom rule categories].
 
-=== Additional resources
+// === Additional resources
 
 // Review the Existing MTA XML Rules
-include::topics/review-existing-rules.adoc[leveloffset=+3]
+// include::topics/review-existing-rules.adoc[leveloffset=+3]
 
 // Fork and Clone the Ruleset GitHub Project
-include::topics/fork-ruleset-repo.adoc[leveloffset=+4]
+//include::topics/fork-ruleset-repo.adoc[leveloffset=+4]
 
 // Important Links
-include::topics/rules-important-links.adoc[leveloffset=+3]
+// include::topics/rules-important-links.adoc[leveloffset=+3]
 
 // **********************************
 // * Appendix: Revision Information *
 // **********************************
-include::topics/templates/revision-info.adoc[]
-=======
+//include::topics/templates/revision-info.adoc[]
+//=======

docs/topics/about-rules.adoc

@@ -7,7 +7,7 @@
 [id="about-rules_{context}"]
 = About {ProductShortName} rules
 
-The {ProductName} ({ProductShortName}) contains rule-based migration tools (analyzers) that analyze the APIs, technologies, and architectures used by the applications you plan to migrate. {ProductShortName} uses analyzer rules internally to extract files from archives, decompile files, scan and classify file types, analyze XML and other file content, analyze the application code, and build the reports.
+The {ProductFullName} contains rule-based migration tools (analyzers) that analyze the APIs, technologies, and architectures used by the applications you plan to migrate. {ProductShortName} uses analyzer rules internally to extract files from archives, decompile files, scan and classify file types, analyze XML and other file content, analyze the application code, and build reports.
 
 {ProductShortName} builds a data model based on the rule execution results and stores component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes.
 
@@ -19,7 +19,7 @@ when(condition)
  tag(tags)
 ----
 
-Although {ProductShortName} provides a comprehensive set of standard migration rules out-of-the-box, you can create your own custom analyzer rules as well. You can use custom rules to identify use of custom libraries or other components that might not be covered by the provided out-of-the-box rulesets.
+Although {ProductShortName} provides a comprehensive set of standard migration rules out-of-the-box, you can create your own custom analyzer rules as well. You can use custom rules to identify the use of custom libraries or other components that are not covered by the provided rulesets.
 
 ifndef::rules-development-guide[]
 If you plan to write your own custom rules, see the {ProductDocRulesGuideURL}[_{RulesDevBookName}_] for detailed instructions.

docs/topics/create-basic-yaml-rule-template.adoc

@@ -16,8 +16,8 @@ when(condition)
 ----
 .Procedure
 
-. In the `/home/<USER>/` directory, create a file containing the basic syntax for YAML rules as follows:
-+
+In the `/home/<USER>/` directory, create a file containing the basic syntax for YAML rules as follows:
+
 [source,terminal]
 ----
 - category: mandatory

docs/topics/create-first-yaml-rule.adoc

@@ -8,7 +8,7 @@
 
 This section guides you through the process of creating and testing your first {ProductShortName} YAML-based rule. This assumes that you have already installed {ProductShortName}. See link:{ProductDocUserGuideURL}/index#installing_and_running_the_cli[Installing and running the CLI] in the _{UserCLIBookName}_ for installation instructions.
 
-In this example, you will create a rule to discover instances where an application defines a `jboss-web.xml` file containing a `<class-loading>` element and to provide a link to the documentation that describes how to migrate the code.
+In this example, you create a rule to discover instances where an application defines a `jboss-web.xml` file containing a `<class-loading>` element and to provide a link to the documentation that describes how to migrate the code.
 
 [id="creating-yaml-file-for-the-rule_{context}"]
 == Creating a YAML file for the rule
@@ -146,7 +146,7 @@ The rule is now complete and looks similar to the following:
 == Installing the rule
 
 .Procedure
-. Point the CLI  to the rule file you created :
+. Point the CLI to the rule file you created :
 +
 [options="nowrap",subs="attributes+"]
 ----

docs/topics/create-yaml-rule.adoc

@@ -12,7 +12,7 @@ Each rule file contains one or more YAML rules. Every rule comprises metadata, c
 
 . Create a `when` condition.
 +
-The `when` condition of a YAML rule can be `provider`, `and` or `or`.
+The `when` condition of a YAML rule can be `provider`, `and`, or `or`.
 
 .. Create a `provider` condition
 +
@@ -125,7 +125,7 @@ The table below lists all available providers, their capabilities, and their fie
 |Yes
 |Finds files with names matching this pattern
 |`hasTags`
-3+>|This is an inline list of string tags. See _Tag Action_ for details on tag format.
+3+>|This is an inline list of string tags. See xref:yaml-rule-actions_rules-development-guide[Tag actions] for details on tag format.
 
 .5+.^|`go`
 |`referenced`

docs/topics/intellij-idea-plugin-run-configuration.adoc

@@ -12,7 +12,7 @@ You can create multiple run configurations to run against each project you impor
 . In the *Projects* view, click the project you want to analyze.
 . On the left side of the screen, click the *{ProductName}* tab.
 +
-If this is your first configuration, the run configuration panel is displayed on the right.
+If this is your first configuration, the *Run configuration* panel is displayed on the right.
 
 . If this is not your first configuration, right-click configuration in the list and select *New configuration*.
 +

docs/topics/mta-about-rules.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// * docs/rules-development-guide/master.adoc
+// * docs/getting-started-guide/master.adoc
+
+:_content-type: CONCEPT
+[id="about-rules_{context}"]
+= About {ProductShortName} rules
+
+The {ProductFullName} contains rule-based migration tools (analyzers) that analyze the APIs, technologies, and architectures used by the applications you plan to migrate. {ProductShortName} uses analyzer rules internally to extract files from archives, decompile files, scan and classify file types, analyze XML and other file content, analyze the application code, and build reports.
+
+{ProductShortName} builds a data model based on the rule execution results and stores component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes.
+
+{ProductShortName} rules use the following rule pattern:
+
+----
+when(condition)
+ message(message)
+ tag(tags)
+----
+
+Although {ProductShortName} provides a comprehensive set of standard migration rules out-of-the-box, you can create your own custom analyzer rules as well. You can use custom rules to identify the use of custom libraries or other components that are not covered by the provided rulesets.
+
+ifndef::rules-development-guide[]
+If you plan to write your own custom rules, see the {ProductDocRulesGuideURL}[_{RulesDevBookName}_] for detailed instructions.
+endif::rules-development-guide[]

docs/topics/templates/document-attributes.adoc

@@ -72,7 +72,7 @@ endif::[]
 :OpenShiftProductNumber: 4.11
 
 :UserCLIBookName: CLI Guide
-:RulesDevBookName: Rule Development Guide
+:RulesDevBookName: Rules Development Guide
 :EclipseCrsGuideTitle: Eclipse Plugin Guide
 :MavenBookName: Maven Plugin Guide
 :IntelliJBookName: IntelliJ IDEA Plugin Guide

docs/topics/yaml-rule-structure-syntax.adoc

@@ -41,7 +41,7 @@ category: mandatory <4>
 [id="yaml-rule-labels_{context}"]
 === Rule labels
 
-Labels are `key=val` pairs specified for rules or rulesets as well as dependencies. For dependencies, a provider adds the labels to the dependencies when retrieving them. Labels on a ruleset are automatically inherited by all the rules that belong to it.
+Labels are `key=val` pairs specified for rules or rulesets, as well as dependencies. For dependencies, a provider adds the labels to the dependencies when retrieving them. Labels on a ruleset are automatically inherited by all the rules that belong to it.
 
 .Label format
 
@@ -88,7 +88,7 @@ The analyzer defines some labels that have special meaning as follows:
 
 .Label selector
 
-The analyzer CLI takes the `--label-selector` field as an option. It is a string expression that supports logical AND, OR and NOT operations. You can use it to filter-in or filter-out rules by their labels.
+The analyzer CLI takes the `--label-selector` field as an option. It is a string expression that supports logical AND, OR, and NOT operations. You can use it to filter-in or filter-out rules by their labels.
 
 _Examples:_
 
@@ -147,7 +147,7 @@ The Java provider in the analyzer can also add an exclude label to a list of pac
 === Rule categories
 
 * `mandatory`
-** You must resolve the issue for a successful migration, otherwise, the resulting application is not expected to build or run successfully. An example of such an issue is proprietary APIs that are not supported on the target platform.
+** You must resolve the issue for a successful migration. Otherwise, the resulting application is not expected to build or run successfully. An example of such an issue is proprietary APIs that are not supported on the target platform.
 * `optional`
 ** If you do not resolve the issue, the application is expected to work, but the results might not be optimal. If you do not make the change at the time of migration, you need to put it on the schedule soon after your migration is completed. An example of such an issue is EJB 2.x code not upgraded to EJB 3.
 * `potential`
@@ -233,7 +233,7 @@ when:
 
 ==== Provider conditions
 
-{ProductShortName} supports multi-language source code analysis. Searching for a specific language in the source code is enabled using the `provider` condition. This condition defines a search query for a specific language provider.  The `provider` condition also specifies which of the provider's "capabilities" to use for analyzing the code.
+{ProductShortName} supports multi-language source code analysis. You can search for a specific language in the source code using the `provider` condition. This condition defines a search query for a specific language provider.  The `provider` condition also specifies which of the provider's capabilities to use for analyzing the code.
 
 The `provider` condition has the form `<provider_name>.<capability>`:
 
@@ -325,7 +325,7 @@ when:
     - "tag1"
     - "tag2"
 ----
-<1> When more than one tags is given, a logical AND is implied.
+<1> When more than one tag is given, a logical AND is implied.
 
 ===== `java` provider
 
@@ -334,7 +334,7 @@ The `java` provider analyzes Java source code.
 This provider has the following capabilities:
 
 * `referenced`
-* `dependency`.
+* `dependency`
 
 .`referenced`
 
@@ -350,7 +350,7 @@ when:
 <1> A RegEx pattern to match, for example, `org.kubernetes.*`
 <2> Specifies the exact location where the pattern needs to be matched, for example, `IMPORT`
 
-The supported locations are the following:
+The following locations are supported:
 
 * `CONSTRUCTOR_CALL`
 * `TYPE`
@@ -411,7 +411,7 @@ when:
 
 ==== Custom variables
 
-Provider conditions can have associated custom variables. You can use custom variables to capture relevant information from the matched line in the source code. The values of these variables are interpolated with data matched in the source code. These values can be used to generate detailed templated messages in a rule’s action (see xref:yaml-rule-actions_{context}[Message actions]). They can be added to a rule in the `customVariables` field:
+Provider conditions can have associated custom variables. You can use custom variables to capture relevant information from the matched line in the source code. The values of these variables are interpolated with data matched in the source code. These values can be used to generate detailed template messages in a rule’s action (see xref:yaml-rule-actions_{context}[Message actions]). They can be added to a rule in the `customVariables` field:
 
 [source,terminal]
 ----
@@ -509,7 +509,7 @@ when:
 
 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.
 
-You can create a ruleset by placing one or more YAML rules in a directory and creating a `ruleset.yaml` file at the directory root. When you pass this directory as input to the {ProductShortName} {CLIName} using the `--rules` option, all rules in this directory are treated as a part of the ruleset defined by `ruleset.yaml` file.
+You can create a ruleset by placing one or more YAML rules in a directory and creating a `ruleset.yaml` file at the directory root. When you pass this directory as input to the {ProductShortName} {CLIName} using the `--rules` option, all rules in this directory are treated as a part of the ruleset defined by the `ruleset.yaml` file.
 
 The `ruleset.yaml` file stores the metadata of the ruleset.
 
@@ -522,4 +522,4 @@ labels: <2>
 ----
 <1> The name must be unique within the provided rulesets.
 
-<2> Ruleset labels are inherited by all rules that belong to the ruleset.
+<2> Ruleset labels are inherited by all rules that belong to the ruleset.