Apply suggestions from code review

Co-authored-by: Valentin Gagarin <valentin@gagarin.work>

source/tutorials/binary-cache-setup.md

@@ -64,7 +64,7 @@ nix-store --generate-binary-cache-key cache.example.com cache-private-key.pem ca
 It should only be accessible for the `nix-serve` daemon.
 (We will set the access rights accordingly as soon as this user exists.)
 
-The content of `cache-public-key.pem` needs to be distributed to everyone who shall access the binary cache.
+Distribute `cache-public-key.pem` to all machines that should be able to access the binary cache.
 
 :::{note}
 The location `/var/secrets/` for keeping the key pair is not a requirement and can be chosen differently.
@@ -109,7 +109,7 @@ Nginx listens on the HTTP port and forwards all connections to `nix-serve`.
 From here, you can set up IPv6 ([IPv6 in the NixOS manual][nixos-ipv6]) if needed.
 If your binary cache is publicly available, please refer to the [NixOS documentation on how to enable HTTPS][nginx-ssl] and adapt the port settings in `networking.firewall.allowedTCPPorts` accordingly.
 
-Add the new NixOS module to your existing `/etc/nixos/configuration.nix`:
+Add the new NixOS module to your existing `configuration.nix`:
 
 ```{code-block} nix
 { config, ... }:

source/tutorials/distributed-builds-setup.md

@@ -8,9 +8,7 @@ myst:
 (distributed-build-setup)=
 # Setting up distributed builds
 
-Nix can distribute builds over multiple remote builders to accelerate builds with parallel execution.
-Nix automatically determines the order and parallelity in which packages may be built.
-Build distribution happens automatically and transparent to users of nix commands if set up correctly.
+Nix can automatically distribute builds over multiple machines to accelerate builds with parallel execution.
 
 ## Introduction
 
@@ -25,7 +23,7 @@ You'll learn how to
 ### What do you need
 
 - The *local machine* (Hostname `localmachine`): The central machine that distributes builds among remote builders.
-- The *remote builder* (hostname `remotebuilder`): One (of possibly many) machines that accept build jobs from the local machine.
+- The *remote machine* (hostname `remotemachine`): One (of possibly many) machines that accept build jobs from the local machine.
 
 The local machine can be configured to distribute among many remote builders.
 
@@ -33,13 +31,13 @@ The local machine can be configured to distribute among many remote builders.
 
 ## Create SSH key pair and prepare local machine
 
-On the *local machine*, run the following command as root to create an SSH key pair:
+On the *local machine*, run the following command as `root` to create an SSH key pair:
 
 ```shell-session
 ssh-keygen -f /root/.ssh/remotebuild
 ```
 
-The local machine will use the private key file to authenticate itself to remote builders.
+The local machine's Nix daemon runs as the `root` user and will need the private key file to authenticate itself to remote machines.
 The remote builder configuration will have the public key to recognize the local machine.
 
 :::{note}
@@ -48,7 +46,7 @@ The name and location of the key pair files can be freely chosen.
 
 ## Set up remote builder
 
-On the *remote builder*, create the file `/etc/nixos/remote-builder.nix`:
+In the configuration for the *remote machine*, create the file `remote-builder.nix`:
 
 ```{code-block} nix
 {
@@ -93,15 +91,14 @@ Activate the new configuration as root:
 
 ### Test authentication
 
-On the *local machine*, run this as root:
+Make sure that the SSH connection and authentication work.
+On the *local machine*, run as `root`:
 
 ```shell-session
 # ssh remotebuild@remotebuilder -i /root/.ssh/remotebuild "echo hello"
 Could not chdir to home directory /home/remotebuild: No such file or directory
 hello
 ```
-
-This command ensures that the SSH connection and authentication work.
 The `Could not chdir to ...` message can be ignored.
 
 It also adds the host key of the remote builder to the `/root/.ssh/known_hosts` file of the local machine.