Apply suggestions from code review

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

Author: cmaglie

docs/sketch-project-file.md

@@ -1,9 +1,11 @@
-Arduino CLI provides support for reproducible builds through the use of build profiles.
+Sketch metadata is defined in a file named `sketch.yaml`. This file is in YAML format.
+
+## Build profiles
 
-## Sketch project file `sketch.yaml` and build profiles.
+Arduino CLI provides support for reproducible builds through the use of build profiles.
 
-A profile is a complete description of all the resources needed to build a sketch. Profiles are defined in a project
-file called `sketch.yaml`. This file is in YAML format and may contain multiple profiles.
+A profile is a complete description of all the resources needed to build a sketch. The sketch project file may contain
+multiple profiles.
 
 Each profile will define:
 
@@ -49,7 +51,7 @@ otherwise below). The available fields are:
 - `<LIB_VERSION>` is the version required for the library, for example, `1.0.0`.
 - `<USER_NOTES>` is a free text string available to the developer to add comments.
 
-A complete example of a `sketch.yaml` may be the following:
+A complete example of a sketch project file may be the following:
 
 ```
 profiles:
@@ -105,7 +107,7 @@ arduino-cli compile --profile nanorp
 ```
 
 In this case, the sketch will be compiled using the core platform and libraries specified in the nanorp profile. If a
-core platform or a library is missing it will be automatically downloaded and installed on the fly in a isolated
+core platform or a library is missing it will be automatically downloaded and installed on the fly in an isolated
 directory inside the data folder. The dedicated storage is not accessible to the user and is meant as a "cache" of the
 resources used to build the sketch.
 

docs/sketch-specification.md

@@ -79,16 +79,12 @@ The `included_libs` key defines the library versions the Arduino Web Editor uses
 Arduino Web Editor specific because all versions of all the Library Manager libraries are pre-installed in Arduino Web
 Editor, while only one version of each library may be installed when using the other Arduino development software.
 
-### Build profiles and reproducible builds
+### Sketch project file
 
-Arduino CLI provides support for reproducible builds through the use of a project file `sketch.yaml`.
+This is an optional file named `sketch.yaml`, located in the root folder of the sketch.
 
 Inside `sketch.yaml` the user can define one or more "profiles": each profile is a description of all the resources
 needed to build the sketch (platform and libraries each pinned to a specific version).
-
-When using a profile to compile, Arduino CLI will install all the required resources in a isolated environment, used
-only for the build, leaving the libraries and platforms installed globally in the system untouched.
-
 For more information see the [sketch project file](sketch-project-file.md) documentation.
 
 ### Secrets