Re: [PATCH] doc: "Introduction" revise and add figure.

[myglc2]

address@hidden (Ludovic Courtès) writes:

> 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).

No problem. I knew I was 'messing with your baby.' But then again you
asked for concrete suggestions, so I gave you some to consider.

> 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.

NP. I am glad parts of it work for you.

> 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,

No doubt. But this may not matter.

> and it also puts too much emphasis on Hydra,

Maybe. But showing that a package can flow directly to the user from
source or thru hydra, a service provided by Guix, is an elemental thing
about Guix that should be put across.

> “system profiles”, and “system services.”

This is an attempt to show the similarity between Guix/GNU/Linux and
GuixSD and also what parts are changed out. And to show the distinction
between per-user profile and system profile. These are elemental to
understanding Guix. They are taken for granted by you but they are quite
foreign to a typical user. And you can't really find your way around the
doc until you understand these points.

Drawing a simple diagram can be a uncomfortable process because it
forces you to throw a lot of details you are very excited about out the
window. But it is an important way to provide an "on-ramp" for new users
and to force oneself to decide what the "elevator story" is. 

As an example of what a failed attempt to provide a useful diagram would
be, consider ...

http://algebraicthunk.net/~dburrows/blog/entry/a-better-map-of-the-apt-state-files/

... This might be relatively more accurate but would be of no use
whatsoever to a new user.

> Anyway, below is the intro as it currently appears in ‘master’.

Thanks, this looks great, but of course eventually, when nirvana has
been reached, all your introduction will say is, "The purpose of GNU
Guix(1) is to allow users to easily install, upgrade, and remove free(2)
GNU and non-GNU software". ;-)

Meanwhile, I think we should take another run at adding a figure for to
the introduction.

- George