Hi! After much hesitation and questions, I ended up pushing something similar in spirit to what you suggest, but with my own words (commit 6f773606812075ee5c6747c3b7f95285254e48f2).
The suggestion you made of describing features “top-down” made a lot of sense to me, esp. compared to the previous one which insisted on the “functional paradigm”, which is not really the first thing newcomers are interested in. However, I felt a few things needed a different explanation. Also, while I agree that illustrations would be helpful, I’m not satisfied with the diagram you proposed. I think the meaning of arrows is unclear, and it also puts too much emphasis on Hydra, “system profiles”, and “system services.” Anyway, below is the intro as it currently appears in ‘master’. Thank you! Ludo’. GNU Guix(1) is a package management tool for the GNU system. Guix makes it easy for unprivileged users to install, upgrade, or remove packages, to roll back to a previous package set, to build packages from source, and generally assists with the creation and maintenance of software environments. Guix provides a command-line package management interface (*note Invoking guix package::), a set of command-line utilities (*note Utilities::), a visual user interface in Emacs (*note Emacs Interface::), as well as Scheme programming interfaces (*note Programming Interface::). Its “build daemon” is responsible for building packages on behalf of users (*note Setting Up the Daemon::) and for downloading pre-built binaries from authorized sources (*note Substitutes::). Guix includes package definitions for many GNU and non-GNU packages, all of which respect the user’s computing freedom (https://www.gnu.org/philosophy/free-sw.html). It is _extensible_: users can write their own package definitions (*note Defining Packages::) and make them available as independent package modules (*note Package Modules::). It is also _customizable_: users can _derive_ specialized package definitions from existing ones, including from the command line (*note Package Transformation Options::). You can install GNU Guix on top of an existing GNU/Linux system where it complements the available tools without interference (*note Installation::), or you can use it as part of the standalone “Guix System Distribution” or GuixSD (*note GNU Distribution::). With GNU GuixSD, you _declare_ all aspects of the operating system configuration and Guix takes care of instantiating the configuration in a transactional, reproducible, and stateless fashion (*note System Configuration::). Under the hood, Guix implements the “functional package management” discipline pioneered by Nix (*note Acknowledgments::). In Guix, the package build and installation process is seen as a _function_, in the mathematical sense. That function takes inputs, such as build scripts, a compiler, and libraries, and returns an installed package. As a pure function, its result depends solely on its inputs—for instance, it cannot refer to software or scripts that were not explicitly passed as inputs. A build function always produces the same result when passed a given set of inputs. It cannot alter the environment of the running system in any way; for instance, it cannot create, modify, or delete files outside of its build and installation directories. This is achieved by running build processes in isolated environments (or “containers”), where only their explicit inputs are visible. The result of package build functions is “cached” in the file system, in a special directory called “the store” (*note The Store::). Each package is installed in a directory of its own in the store—by default under ‘/gnu/store’. The directory name contains a hash of all the inputs used to build that package; thus, changing an input yields a different directory name. This approach is the foundation for the salient features of Guix: support for transactional package upgrade and rollback, per-user installation, and garbage collection of packages (*note Features::). ---------- Footnotes ---------- (1) “Guix” is pronounced like “geeks”, or “ɡiːks” using the international phonetic alphabet (IPA).
