Updated and refined documentation

docs/configuration.md

@@ -8,7 +8,8 @@
   - `data` - directory used to store Boards/Library Manager index files and Boards Manager platform installations.
   - `downloads` - directory used to stage downloaded archives during Boards/Library Manager installations.
   - `user` - the equivalent of the Arduino IDE's ["sketchbook" directory][sketchbook directory]. Library Manager
-    installations are made to the `libraries` subdirectory of the user directory.
+    installations are made to the `libraries` subdirectory of the user directory. Users can manually install 3rd party
+    platforms in the `hardware` subdirectory of the user directory.
   - `builtin.libraries` - the libraries in this directory will be available to all platforms without the need for the
     user to install them, but with the lowest priority over other installed libraries with the same name, it's the
     equivalent of the Arduino IDE's bundled libraries directory.
@@ -45,6 +46,25 @@
 - `network` - configuration options related to the network connection.
   - `proxy` - URL of the proxy server.
 
+### Default directories
+
+The following are the default directories selected by the Arduino CLI if alternatives are not specified in the
+configuration file.
+
+- The `directories.data` default is OS-dependent:
+
+  - on Linux (and other Unix-based OS) is: `{HOME}/.arduino15`
+  - on Windows is: `{HOME}/AppData/Local/Arduino15`
+  - on MacOS is: `{HOME}/Library/Arduino15`
+
+- The `directories.download` default is `{directories.data}/staging`. If the value of `{directories.data}` is changed in
+  the configuration the user-specified value will be used.
+
+- The `directories.user` default is OS-dependent:
+  - on Linux (and other Unix-based OS) is: `{HOME}/Arduino`
+  - on Windows is: `{DOCUMENTS}/Arduino`
+  - on MacOS is: `{HOME}/Documents/Arduino`
+
 ## Configuration methods
 
 Arduino CLI may be configured in three ways:

docs/platform-specification.md

@@ -5,31 +5,62 @@ Platforms add support for new boards to the Arduino development software. They a
 [Boards Manager](package_index_json-specification.md) or manual installation to the _hardware_ folder of Arduino's
 sketchbook folder (AKA "user directory").<br> A platform may consist of as little as a single configuration file.
 
-## Hardware Folders structure
+## Platform installation directories
 
-The new hardware folders have a hierarchical structure organized in two levels:
+If the platforms are installed using the Board Manager the installation directory location will be as follow:
 
-- the first level is the vendor/maintainer
-- the second level is the supported architecture
+`{directories.data}/packages/{VENDOR_NAME}/hardware/{ARCHITECTURE}/{VERSION}/...`
 
-A vendor/maintainer can have multiple supported architectures. For example, below we have three hardware vendors called
-"arduino", "yyyyy" and "xxxxx":
+- `{directories.data}` is the data directory as specified in the
+  [configuration file](configuration.md#default-directories).
+- `{VENDOR_NAME}` is the identifier of the vendor/maintainer of the platform.
+- `{ARCHITECTURE}` is the architecture of the CPU used in the platform.
+- `{VERSION}` is the platform version.
 
+Alternatively, a platform may be manually installed by the user inside the Sketchbook/user directory as follows:
+
+`{directories.user}/hardware/{VENDOR_NAME}/{ARCHITECTURE}/...`
+
+- `{directories.user}` is the user directory as specified in the
+  [configuration file](configuration.md#default-directories).
+- `{VENDOR_NAME}` is the identifier of the vendor/maintainer of the platform.
+- `{ARCHITECTURE}` is the architecture of the CPU used in the platform.
+
+A vendor/maintainer can have multiple supported architectures.
+
+For example, below we have four platforms downloaded from three hypothetical hardware vendors called "arduino", "foo"
+and "bar", and installed using the Board Manager:
+
+```
+{directories.data}/packages/arduino/hardware/avr/1.2.3/...
+{directories.data}/packages/arduino/hardware/sam/1.4.5/...
+{directories.data}/packages/foo/hardware/avr/1.0.2/...
+{directories.data}/packages/bar/hardware/avr/1.1.0/...
 ```
-hardware/arduino/avr/...     - Arduino - AVR Boards
-hardware/arduino/sam/...     - Arduino - SAM (32bit ARM) Boards
-hardware/yyyyy/avr/...       - Yyy - AVR
-hardware/xxxxx/avr/...       - Xxx - AVR
+
+If the same platform were manually installed by the user, he should have unpacked them inside the following directories:
+
+```
+{directories.user}/hardware/arduino/avr/...
+{directories.user}/hardware/arduino/sam/...
+{directories.user}/hardware/foo/avr/...
+{directories.user}/hardware/bar/avr/...
 ```
 
-The vendor "arduino" has two supported architectures (AVR and SAM), while "xxxxx" and "yyyyy" have only AVR.
+In this latter case the version is omitted.
+
+We can also see that the vendor "arduino" has two supported architectures (AVR and SAM), while "foo" and "bar" have only
+AVR.
+
+### Notes about choosing the architecture name
 
 Architecture values are case sensitive (e.g. `AVR` != `avr`).
 
-If possible, follow existing architecture name conventions when creating hardware packages. Use the vendor folder name
-to differentiate your package. The architecture folder name is used to determine library compatibility and to permit
-referencing resources from another core of the same architecture, so use of a non-standard architecture name can have a
-harmful effect.
+Platform developers should follow the existing architecture name conventions when creating hardware packages, if you
+need to differentiate your package use the vendor/maintainer folder name to do so.
+
+The architecture name is used to determine the libraries compatibility and to permit referencing resources from another
+platform of the same architecture. Use of a non-standard architecture name can have a harmful effect.
 
 ## Architecture configurations
 

docs/pluggable-discovery-specification.md

@@ -312,7 +312,8 @@ The `properties` associated to a port can be used to identify the board attached
   "candidate" board attached to that port.
 
 Some port `properties` may not be precise enough to uniquely identify a board, in that case more boards may match the
-same set of `properties`, that's why we called it "candidate".
+same set of `properties`, that's why we called it "candidate". The board identification properties should be used only
+if they allows to match the board model beyond any doubt.
 
 Let's see an example to clarify things a bit, let's suppose that we have the following `properties` coming from the
 serial discovery:
@@ -392,6 +393,13 @@ myboard.upload_port.1.apples=40
 will match on both `pears=20, apples=30` and `pears=30, apples=40` but not `pears=20, apples=40`, in that sense each
 "set" of identification properties is independent from each other and cannot be mixed for port matching.
 
+#### An important note about `vid` and `pid`
+
+The board identification properties should be used only if they allows to match the board model beyond any doubt.
+Sometimes a board do not expose a unique vid/pid combination, this is the case for example if a USB-2-serial converter
+chip is used (like the omnipresent FT232 or CH340): those chips exposes their specific vid/pid that will be the same for
+all the other boards using the same chip. In such cases the board identification properties should NOT be used.
+
 #### Identification of board options
 
 [Custom board options](platform-specification.md#custom-board-options) can also be identified.