diff --git a/docs/platform-specification.md b/docs/platform-specification.md
index dfd85422902..63f4fea4cc6 100644
--- a/docs/platform-specification.md
+++ b/docs/platform-specification.md
@@ -26,31 +26,34 @@ Alternatively, a platform may be manually installed by the user inside the Sketc
 - `{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.
+A vendor/maintainer may 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:
+Let's see an example, below we have a bunch of platforms downloaded from three hardware vendors `arduino`, `adafruit`
+and `esp32`, 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/...
+{directories.data}/packages/arduino/hardware/avr/1.8.6/...
+{directories.data}/packages/arduino/hardware/esp32/2.0.18-arduino.5/...
+{directories.data}/packages/arduino/hardware/nrf52/1.4.5/...
+{directories.data}/packages/adafruit/hardware/nrf52/1.6.1/...
+{directories.data}/packages/esp32/hardware/esp32/3.0.7/...
 ```
 
-If the same platform were manually installed by the user, he should have unpacked them inside the following directories:
+In this example three architectures have been installed from the vendor `arduino` (`avr`, `esp32` and `nrf52`), and one
+from `adafruit` and `esp32` (`nrf52` and `esp32` respectively). Note that the vendor `esp32` has the same name of the
+architecture `esp32`.
+
+If the user manually installed the same platforms, they should have unpacked them in the following directories:
 
 ```
 {directories.user}/hardware/arduino/avr/...
-{directories.user}/hardware/arduino/sam/...
-{directories.user}/hardware/foo/avr/...
-{directories.user}/hardware/bar/avr/...
+{directories.user}/hardware/arduino/esp32/...
+{directories.user}/hardware/arduino/nrf52/...
+{directories.user}/hardware/adafruit/nrf52/...
+{directories.user}/hardware/esp32/esp32/...
 ```
 
-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.
+In this latter case the version must be omitted.
 
 ### Notes about choosing the architecture name