Enhance the documentation and rearrange README.md (#71)

* streamline `README.md`

* moved old `README.md` in the docs folder

* split `docs/README.md` in different markdown files

* applied suggestions by @per1234 💚

* Update README.md

Co-authored-by: per1234 <accounts@perglass.com>

Co-authored-by: per1234 <accounts@perglass.com>

README.md

@@ -1,124 +1,32 @@
-# Firmware/Certificates updater for WINC and NINA Wifi module
+# Arduino Firmware Uploader
 
-Use this tool to update the firmware and/or add SSL certificates for any WINC, NINA module.
+The Arduino Firmware Uploader is a tool made to update the firmware and/or add SSL certificates for any Arduino board
+equipped with WINC or NINA Wi-Fi module.
 
-## Install
+[![tests-badge]](https://github.com/arduino/arduino-fwuploader/actions/workflows/test.yaml)
+[![docs-badge]](https://github.com/arduino/arduino-fwuploader/actions/workflows/publish-docs.yaml)
 
-You can download the Firmware/Certificates updater here:
+## Docs
 
-https://github.com/arduino/arduino-fwuploader/releases/latest
+For guidance on installation and development, see the [User documentation]
 
-## Usage
+## Quickstart
 
-### Firmware Flashing
-
-Extract the zip file and, to update a mkr 1010, run:
-
-```
-./arduino-fwuploader firmware flash -b arduino:samd:mkrwifi1010 -a /dev/ttyACM0
-```
-
-You just have to specify the fqbn (`-b` or `--fqbn`) of the board and the serial port (`-a` or `--address`) The firmware
-uploader will take care of fetching everything is required to perform the update process. If no module and version are
-specified **the latest version of the firmware** will be used.
-
-If you want to flash a specific version of a firmware you can use the `-m` or `--module` flag
-
-For example to flash a MKR1000 with 19.6.1 version of the firmware you can run something like:
-
-```
-./arduino-fwuploader firmware flash -b arduino:samd:mkr1000 -a /dev/ttyACM0 -m WINC1500@19.6.1
-```
-
-There is also a retry mechanism bundled in the tool because the flashing process sometimes can be a bit unreliable. For
-example to update a Nano RP2040 Connect with the retry set to 2 you can use:
-
-```
-./arduino-fwuploader firmware flash --fqbn arduino:mbed_nano:nanorp2040connect -a /dev/ttyACM0 --retries 2
-```
-
-It's possible also to list the available firmwares for every board/module with:
-
-```
-./arduino-fwuploader firmware list
-```
-
-but you can also filter the results by specifying the `-b` or `--fqbn` flag
-
-The tool offers the ability to print output in json, with the `--format json`
-
-### Certificates
-
-The tool offers also the ability to flash SSL certificates to a board:
-
-```
-/arduino-fwuploader flash -b arduino:samd:nano_33_iot" -a COM10 -u arduino.cc:443 -u google.cc:443
-```
-
-or you can specify a path to a file with `-f`
-
-### Command line options
-
-The full list of command line options can be obtained with the `-h` option: `./arduino-fwuploader -h`
-
-```
-Arduino Firmware Uploader (arduino-fwuploader).
-
-Usage:
-  arduino-fwuploader [command]
-
-Examples:
-  ./arduino-fwuploader <command> [flags...]
-
-Available Commands:
-  certificates Commands to operate on certificates.
-  firmware     Commands to operate on firmwares.
-  help         Help about any command
-  version      Shows version number of arduino-fwuploader.
-
-Flags:
-      --format string       The output format, can be {text|json}. (default "text")
-  -h, --help                help for arduino-fwuploader
-      --log-file string     Path to the file where logs will be written
-      --log-format string   The output format for the logs, can be {text|json}.
-      --log-level string    Messages with this level and above will be logged. Valid levels are: trace, debug, info, warn, error, fatal, panic (default "info")
-  -v, --verbose             Print the logs on the standard output.
-
-Use "arduino-fwuploader [command] --help" for more information about a command.
-```
-
-## How to build the tools from source file
-
-To build we use [task](https://taskfile.dev/) for simplicity. From the sources root directory run:
-
-```
-task dist:<OS>_<ARCH>
-```
-
-Where <OS> could be one of: `macOS`,`Windows`,`Linux`. And <ARCH>: `32bit`, `64bit`, `ARM` or `ARM64`
-
-This will create the `arduino-fwuploader` executable.
+1. [Install] the Arduino Firmware Uploader
+2. Follow the [Usage] guide to check out what the tool can do
+3. Browse the [Commands reference] to see all the available commands
 
 ## Security
 
-If you think you found a vulnerability or other security-related bug in this project, please read our [security
-policy][security-policy] and report the bug to our Security Team 🛡️ Thank you!
+If you think you found a vulnerability or other security-related bug in this project, please read our [security policy]
+and report the bug to our Security Team 🛡️ Thank you!
 
 e-mail contact: security@arduino.cc
 
-## License
-
-Copyright (c) 2015-2021 Arduino LLC. All right reserved.
-
-This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public
-License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later
-version.
-
-This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
-warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
-details.
-
-You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the
-Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
-[security-policy]: https://github.com/arduino/arduino-fwuploader/security/policy
+[tests-badge]: https://github.com/arduino/arduino-fwuploader/actions/workflows/test.yaml/badge.svg
+[docs-badge]: https://github.com/arduino/arduino-fwuploader/actions/workflows/publish-docs.yaml/badge.svg
+[security policy]: https://github.com/arduino/arduino-fwuploader/security/policy
+[user documentation]: https://arduino.github.io/arduino-fwuploader/
+[install]: https://arduino.github.io/arduino-fwuploader/dev/installation
+[usage]: https://arduino.github.io/arduino-fwuploader/dev/usage
+[commands reference]: https://arduino.github.io/arduino-fwuploader/dev/commands/arduino-fwuploader/

docs/index.md

@@ -0,0 +1,14 @@
+The Arduino Firmware Uploader is a tool made to update the firmware and/or add SSL certificates for any Arduino board
+equipped with WINC or NINA Wi-Fi module.
+
+## Installation
+
+You have several options to install the latest version of the Arduino Firmware Uploader on your system, see the
+[installation] page.
+
+## Getting started
+
+Follow the [Usage guide] to see how to use the most common CLI commands.
+
+[installation]: installation.md
+[usage guide]: usage.md

docs/installation.md

@@ -0,0 +1,17 @@
+## Install
+
+You can download the Arduino Firmware Uploader directly from the GitHub release page:
+
+https://github.com/arduino/arduino-fwuploader/releases/latest
+
+### How to build the tools from source file
+
+To build we use [task](https://taskfile.dev/) for simplicity. From the sources root directory run:
+
+```
+task dist:<OS>_<ARCH>
+```
+
+Where <OS> could be one of: `macOS`,`Windows`,`Linux`. And <ARCH>: `32bit`, `64bit`, `ARM` or `ARM64`
+
+This will create the `arduino-fwuploader` executable.

docs/usage.md

@@ -0,0 +1,60 @@
+## Usage
+
+### Firmware Flashing
+
+First [install] the Arduino Firmware Uploader. Extract the zip file and, for example, to update the NINA module present
+on the Arduino MKR WiFi 1010, run:
+
+```
+./arduino-fwuploader firmware flash -b arduino:samd:mkrwifi1010 -a /dev/ttyACM0
+```
+
+You just have to specify the FQBN (`-b` or `--fqbn`) of the board and the serial port (`-a` or `--address`). The
+firmware uploader will take care of fetching everything is required to perform the update process. If no module and
+version are specified **the latest version of the firmware** will be used.
+
+If you want to flash a specific version of a firmware you can use the `-m` or `--module` flag
+
+For example to flash the WINC module present on the MKR 1000 with version 19.6.1 of the firmware you can run something
+like:
+
+```
+./arduino-fwuploader firmware flash -b arduino:samd:mkr1000 -a /dev/ttyACM0 -m WINC1500@19.6.1
+```
+
+There is a retry mechanism because the flashing process uses serial communication, which sometimes can be a bit
+unreliable. The retry flag is set by default to 9 retries, but it's possible to overwrite it for whatever reason. For
+example to update a Nano RP2040 Connect with the retry set to 2 you can use:
+
+```
+./arduino-fwuploader firmware flash --fqbn arduino:mbed_nano:nanorp2040connect -a /dev/ttyACM0 --retries 2
+```
+
+It's possible to list the available firmwares for every board/module with:
+
+```
+./arduino-fwuploader firmware list
+```
+
+but you can also filter the results by specifying the `-b` or `--fqbn` flag
+
+The tool offers the ability to print output in JSON, with the `--format json` flag
+
+### Certificates
+
+The tool offers also the ability to flash SSL certificates to a module:
+
+```
+./arduino-fwuploader certificates flash -b arduino:samd:nano_33_iot" -a COM10 -u arduino.cc:443 -u google.cc:443
+```
+
+or you can specify a path to a file with `-f` instead of the URL of the certificate
+
+### Command line options
+
+The full list of command line options can be obtained with the `-h` option: `./arduino-fwuploader -h`
+
+For further information you can use the [command reference]
+
+[install]: installation.md
+[command reference]: commands/arduino-fwuploader.md

mkdocs.yml

@@ -61,7 +61,9 @@ extra:
 
 # Navigation
 nav:
-  - Documentation Home: README.md
+  - Documentation Home: index.md
+  - Installation: installation.md
+  - Usage: usage.md
   - Command reference:
       - arduino-fwuploader: commands/arduino-fwuploader.md
       - certificates: commands/arduino-fwuploader_certificates.md