We're working through a list of feedback one item at a time:
https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

We have completed an item and are ready to work on the next one:

#+begin_quote
,** Binary Installation L88 and L95

~root is weird. Should be root or simply ~ for the user profile which would be root as root user.
#+end_quote

I agree.  I found it weird at first, too.

Two thoughts:

1. The use of "~root" is intentional
2. Section 2.1 Binary Install can be refactored to remove the reported confusion as well as the tarpit of shell related details

*1. The use of "~root" is intentional*

According to the Bash info and man pages, "~root" is a TILDE-PREFIX with "root" as the LOGIN NAME.  The TILDE-PREFIX is replaced with the home directory associated with the specified LOGIN NAME.

Using "~root" solves the problem of operations happening in the wrong location.  It ensures that commands reference the 'root' user's home directory.

- (original issue) https://lists.gnu.org/archive/html/guix-devel/2015-06/msg00085.html
- (separate issue) https://bugs.gnu.org/30728

*2. Section 2.1 Binary Install needs refactoring*

The Binary Installation section tries to solve the problem of guiding readers to install Guix as quickly and painlessly as possible.  This began as a step-by-step process which was later automated by 'guix-install.sh'.  Over 6 years, 12 people have worked to make 'guix-install.sh' robust.  Because of these efforts, Section 2.1 Binary Installation has effectively become high level documentation for how 'guix-install.sh' works.

Like any code comment tends to drift out of sync with the source code, the current presentation of binary installations has become inconsistent and redundant.  Using 'guix-install.sh' is the recommended method for binary installation.  It's the first thing mentioned by Section 2 Installation and one of the first things mentioned by Section 2.1 Binary Installation.  It's inconsistent to say, "This is how to do it" and then proceed to explain how to *not* use the recommended method.

Key information, like the recommended installation method and the definition of "foreign distro", are improperly hidden inside notes.  Note blocks act as comments which, by definition, are secondary to the main point.  The main point is to use 'guix-install.sh' on foreign distros which don't provide their own packages for Guix.

The attached diff addresses these issues.  It fixes the root issue (pun intended) of whether or not to expect readers to understand '~root', as well as unmentioned issues also related to shell-specific knowledge like, "What does it mean to 'source'?"  Readers interested in those details may read the code for 'guix-install.sh'.

The diff does the following:

- Clarifies at the top level that installing on a foreign distro has two methods: using packaged binaries and building from source
- Places the overwrite warning at the top level node and binary installation level node
- Moves the definition of "foreign distro" out of quotation
- Moves the foreign distro installation instructions out of quotation
- Summarizes the steps 'guix-install.sh' follows rather than trying to detail them
- Splits the requirements between system requirements for binary installations, GNU/Linux or GNU/Hurd, and requirements for running 'guix-install.sh', tar, wget, Xz
- Removes redundant instructions to use 'guix-install.sh'
- Places directions for 'guix-install.sh' after directions to use distribution-specific package managers, giving preference to those simpler install processes over the more manual 'guix-install.sh' process