Re: [doc RFC] Tame the Guix profile blizzard?

[Nils Gillmann <ng0@n0.is>]

George Clemmer transcribed 1.4K bytes:
> ISTM our doc is a veritable "Profile Blizzard."
> 
> 
> The term occurs 173 times in guix.texi
> 
> 
> The "user profile" is referred to in multiple ways:
> 
>  (guix) Application Setup: "your Guix profile"
> 
>  (guix) Features: 'own “profile”', "per-user profiles", "their profile"
> 
>  (guix) Invoking guix package: "user’s own profile", "user’s default
>  profile", ‘$HOME/.guix-profile’
> 
>  (guix) Invoking guix environment: "package profile"
> 
> 
> The "system profile" is referred to in multiple ways:
> 
>  (guix) Using the Configuration System: "Globally-installed packages"
> 
>  (guix) operating-system Reference: "global profile",
>  ‘/run/current-system/profile’
> 
>  (guix) Networking Services: "system profile"
> 
> 
> An unnamed type of "environment profile" is produced by 'guix
> environment'
> 
>  (guix) Invoking guix environment" ‘GUIX_ENVIRONMENT’ variable
> 
> 
> An unnamed type of "custom profile" is produced by the 'guix package' -p
> option.
> 
> 
> (guix) Top mentions only an entirely different use of the term:
> 
>  * Invoking guix size::          Profiling disk usage.
> 
> 
> (guix) Concept Index contains only (guix) Invoking guix package
> references.
> 
> 
> ISTM we can improve this situation as follows:
> 
> 1) agree on a canonical term to use for the 4 types of profiles
> 
> 2) update the doc accordingly
> 
> 3) add a top level discussion of profiles

  4) before each profile kind is used for the first time,
     make use of something like this for the brief introduction
     of it again (our manual is not very long, but it is still
     long):

@cartouche
@quotation Note
In the following ``spacejump'' refers to …
@end quotation
@end cartouche

this renders at least in HTML and PDF output of texinfo. I haven't
used this very much so far.

A visual example can be found in 'Exchange', Chapter 'Configuration'
in https://docs.taler.net/

> WDYT? - George
>