Update documentation home page according to blog post review

This documentation is based on the release announcement blog post, so the improvements made to that document should be
mirrrored here.

Author: per1234

docs/index.md

@@ -2,8 +2,7 @@
 projects.
 
 Its focus is on the structure, metadata, and configuration of Arduino projects, rather than the code. Rules cover
-[specification](https://arduino.github.io/arduino-cli/latest/library-specification) compliance, Library Manager
-submission [requirements](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ), and best practices.
+specification compliance, Library Manager submission requirements, and best practices.
 
 ## Installation
 
@@ -17,44 +16,47 @@ Once installed, you only need to open a terminal at your project folder and run
 arduino-lint
 ```
 
-This will automatically search for projects, detect their type, and run the appropriate checks on them.
+This will automatically detect the project type and check it against the relevant rules.
 
 The default configuration of **arduino-lint** provides for the most common use case, but you have the option of changing
 settings via [command line flags](commands/arduino-lint.md):
 
 ### Compliance setting
 
-The `--compliance` flag allows you to configure the strictness of the checks.
+The `--compliance` flag allows you to configure the strictness of the applied rules. The three compliance level values
+accepted by this flag are:
 
-`--compliance permissive` will cause the checks to fail only when severe problems are found. Although a project that
-passes at the permissive setting will work with the current Arduino development software versions, it may not be fully
-specification-compliant, risking incompatibility or a poor experience for the users.
-
-`--compliance specification`, the default setting, enforces compliance with the official Arduino project specifications.
-
-`--compliance strict` enforces best practices, above and beyond the minimum requirements for specification compliance.
-Use this setting to ensure the best experience for the users of the project.
+- `permissive` - failure will occur only when severe rule violations are found. Although a project that passes at the
+  permissive setting will work with the current Arduino development software versions, it may not be fully
+  specification-compliant, risking incompatibility or a poor experience for the users.
+- `specification` - the default setting, enforces compliance with the official Arduino project specifications
+  ([sketch](https://arduino.github.io/arduino-cli/latest/sketch-specification/),
+  [library](https://arduino.github.io/arduino-cli/latest/library-specification/),
+  [platform](https://arduino.github.io/arduino-cli/latest/platform-specification/)).
+- `strict` - enforces best practices, above and beyond the minimum requirements for specification compliance. Use this
+  setting to ensure the best experience for the users of the project.
 
 ### Library Manager setting
 
-Arduino Library Manager is the best way to provide installation and updates of Arduino libraries. In order to be
-accepted for inclusion in Library Manager, a library is required to meet some requirements.
+[Arduino Library Manager](https://www.arduino.cc/en/guide/libraries#toc3) is the best way to provide installation and
+updates of Arduino libraries. In order to be accepted for inclusion in Library Manager, a library is required to meet
+[some requirements](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ).
 
 **arduino-lint** provides checks for these requirements as well, controlled by the `--library-manager` flag.
 
-The checks for the Library Manager submission requirements are enabled via `--library-manager submit`. Even if your
-library isn't yet ready to be added to Library Manager, it's a good idea to use this setting to ensure no
-incompatibilities are introduced.
+The Library Manager submission-specific rules are enabled via `--library-manager submit`. Even if your library isn't yet
+ready to be added to Library Manager, it's a good idea to use this setting to ensure no incompatibilities are
+introduced.
 
 Once your library is in the Library Manager index, each release is automatically picked up and made available to the
-Arduino community. Releases are also subjected to special checks, which must pass for it to be added to the index. The
-command `arduino-lint --library-manager update` will tell you whether your library will pass these checks.
+Arduino community. Releases are also subject to special rules. The command `arduino-lint --library-manager update` will
+tell you whether your library is compliant with these rules.
 
 ### Integration
 
 The `--format` flag configures the format of **arduino-lint**'s output. The default `--format text` setting provides
 human readable output. For automation or integration with other tools, the machine readable output provided by
-`--format json` may be more convenient. This setting exposes all the details of the checks that are run.
+`--format json` may be more convenient. This setting exposes every detail of the rules that were applied.
 
 The `--report-file` flag causes **arduino-lint** to write the JSON output to the specified file.
 
@@ -71,14 +73,15 @@ Additional configuration options intended for internal use or development can be
 ## Continuous integration
 
 **arduino-lint** would be a great addition to your
-[continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) system. Running the checks after each
-change to the project will allow you to identify any problems that were introduced.
+[continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) system. Running the tool after each
+change to the project can allow you to identify any problems that were introduced.
 
-This is easily done by using the `arduino/arduino-lint-action` GitHub Actions action:
+This is easily done by using the `arduino/arduino-lint-action`
+[GitHub Actions](https://docs.github.com/en/free-pro-team@latest/actions) action:
 https://github.com/arduino/arduino-lint-action
 
-Add a simple workflow file to the repository of your Arduino project and the checks will automatically be run on every
-pull request and push.
+Add [a simple workflow file](https://github.com/arduino/arduino-lint-action#usage) to the repository of your Arduino
+project and GitHub will automatically run arduino-lint on every pull request and push.
 
 ## Support and feedback