Merge pull request #150 from arduino/per1234/update-docs-index

Update documentation home page according to blog post review

Author: per1234

Diff for: 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