Re: [PATCH] Quick-start guide

[myglc2 <myglc2@gmail.com>]

Leo Famulari <leo@famulari.name> writes:

> On Sat, Jun 11, 2016 at 06:43:21AM -0700, yoosty@gmail.com wrote:
>> Upon further reflection.. The Guix manual might not be an appropriate place
>> for such a guide. If the Guix manual isn't a good place for such a set of
>> instructions, do you have any suggestions for a location (blog, etc)?

I think your first intuition was correct: this information should be
added to the manual.

> There is this useful wiki managed by Raymond Nicholson:
> https://gitlab.com/rain1/guix-wiki/wikis/home
>
> Although, I'd like to echo Ludovic's question, and also say that the
> goal of the manual is to be completely sufficient for first-timers and
> experienced users alike.

This is the correct goal, but the manual as it stands is problematic for
first-time users for reasons such as: it's overwhelmingly copious;
information is "shredded" into different sections; the is confusing
terminology; finding one's way around is difficult; there is virtually
no guidance of what to read first or how to proceed.

I see this patch as an attempt to address some of these difficulties.

> I find the phenomenon of 3rd party wikis giving instructions on how to
> use some piece of software to be a dismaying "antipattern". And, the
> situation only gets worse as people send documentation to the 3rd
> party wiki instead of to the software project in questoin.

To avoid the "antipattern" we need to make Guix documentation more
friendly for first-time users and be more _receptive_ to comments and
patches from first-time users.

I suggest we add a new "Getting Started" section between "Introduction"
and "Installation". "Getting Started" should initially include a
discussion of how to decide whether to install Guix or GuixSD and
quick-start sections for each.

This patch should be used as the "GuixSD quick-start" section.