[PATCH] Quick-start guide

[PATCH] Quick-start guide

[yoosty]

[-- Attachment #1: Type: text/plain, Size: 4149 bytes --]

Howdy!

This is my first submission, please be gentle ;)

Input is definitely welcome.


diff --git a/doc/contributing.texi b/doc/contributing.texi
index 208c6af..46c652f 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -18,6 +18,7 @@ the @file{CODE-OF-CONDUCT} file in the source tree.
 @menu
 * Building from Git::           The latest and greatest.
 * Running Guix Before It Is Installed::  Hacker tricks.
+* Quick Setup::                 The quick and easy tools
 * The Perfect Setup::           The right tools.
 * Coding Style::                Hygiene of the contributor.
 * Submitting Patches::          Share your work.
@@ -153,6 +154,75 @@ the @file{/root/.config/guix/latest} symlink to point
to
 @command{guix} as your user does.}


+@node Quick Setup
+@section Quick Setup
+
+So you just want the quick-and-dirty guide? Assuming you have some
familiarity
+with GNU/Linux systems in general and have installed one several times
before
+you can probably get started with a few notes while citing
+@pxref{GNU Distribution} as necessary. As this is a quick-setup guide
we'll use
+some example defaults.
+
+The general idea is that you will:
+@itemize
+@item @uref{https://gnu.org/software/guix/download/, Download} the USB
installer
+@item Transfer the image to a USB stick (@pxref{USB Stick Installation})
+using dd
+@item Boot the USB stick
+@item Configure @pxref{Preparing for Installation,Networking}
+@item Set your @xref{Preparing for Installation,Disk Partitioning}
+(using an msdos label instead of a gpt label might be easier at the moment)
+@item Mount your partitions (e.g. /mnt)
+@item Run (again, e.g. /mnt) @command{herd start cow-store /mnt}
+@item Create a system configuration file using
+@xref{Proceeding with the Installation} and
+@xref{Using the Configuration System} as guides. It is suggested to start
+with the bare-bones template as you can easily re-configure your system
+once it is up.
+@item Using /mnt/root/guix_configs/config00.scm as the example config file
+and /mnt as the example install mount point, run
+@command{guix system init /mnt/root/guix_configs/config00.scm /mnt}
+@item Cross your fingers and grab a beer
+@item If you're using reasonably new hardware and a bare-bones config
+then guix should be done before your beverage and you can run
+@command{reboot}
+@end itemize
+
+Now you should be ready to rock! Don't forget to set your user passwords.
+
+Of course, you're not here just to have a working system are you, you want
+to dive in to the source, right? Let's take a quick look at that as well.
+This guide assumes that you have at least perused @pxref{Building from
Git}.
+First you might want to head to
+@uref{http://git.savannah.gnu.org/cgit/guix.git, the Guix Git page} and
browse
+around. We're going to assume that you utilized a bare-bones config as per
the
+quick install guide above. In this short example you will be shown simply
+how to change the release version of Guix (not something you will likely do
+but an easy and fun example).
+
+@itemize
+@item Install git in to your user's profile: @command{guix package
--install git}
+@item Create a directory for your git checkout (e.g. @command{mkdir
~/git_repos})
+@item Clone the Guix repository:
+@command{cd ~/git_repos/; git clone git://git.sv.gnu.org/guix.git; cd guix}
+@item To make the simple version change:
+@code{AC_INIT([GNU Guix], [0.10.0], [bug-guix@@gnu.org], [guix],}
+to
+@code{AC_INIT([GNU Guix], [0.10.42], [bug-guix@@gnu.org], [guix],}
+@item Check your change with: @command{git diff configure.ac}
+@item Let Guix set up your Guix build
+environment:@command{guix environment guix}
+@item Build Guix:
+@command{./bootstrap ; ./configure --localstatedir=/var ; make}
+@item Run the daemon in a pre-installation environment:
+@command{sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild}
+@item Switch to a new terminal
+@item Check the pre-installation environement daemon's version:
+@command{./git_repos/guix/pre-inst-env guix --version}
+@item Your version output should be updated!
+@end itemize
+
+
 @node The Perfect Setup
 @section The Perfect Setup


-- 

   .:Justin:.

[-- Attachment #2: Type: text/html, Size: 4959 bytes --]

Re: [PATCH] Quick-start guide

[Ludovic Courtès]

Hello!

yoosty@gmail.com skribis:

> +@node Quick Setup
> +@section Quick Setup
> +
> +So you just want the quick-and-dirty guide? Assuming you have some
> familiarity
> +with GNU/Linux systems in general and have installed one several times
> before
> +you can probably get started with a few notes while citing
> +@pxref{GNU Distribution} as necessary. As this is a quick-setup guide
> we'll use
> +some example defaults.
> +
> +The general idea is that you will:
> +@itemize
> +@item @uref{https://gnu.org/software/guix/download/, Download} the USB
> installer
> +@item Transfer the image to a USB stick (@pxref{USB Stick Installation})
> +using dd
> +@item Boot the USB stick
> +@item Configure @pxref{Preparing for Installation,Networking}
> +@item Set your @xref{Preparing for Installation,Disk Partitioning}
> +(using an msdos label instead of a gpt label might be easier at the moment)
> +@item Mount your partitions (e.g. /mnt)
> +@item Run (again, e.g. /mnt) @command{herd start cow-store /mnt}
> +@item Create a system configuration file using
> +@xref{Proceeding with the Installation} and
> +@xref{Using the Configuration System} as guides. It is suggested to start
> +with the bare-bones template as you can easily re-configure your system
> +once it is up.
> +@item Using /mnt/root/guix_configs/config00.scm as the example config file
> +and /mnt as the example install mount point, run
> +@command{guix system init /mnt/root/guix_configs/config00.scm /mnt}
> +@item Cross your fingers and grab a beer
> +@item If you're using reasonably new hardware and a bare-bones config
> +then guix should be done before your beverage and you can run
> +@command{reboot}
> +@end itemize

[...]

At first sight this seems redundant with the “System Installation”
section, no?

What shortcoming are you trying to address?

Thanks for helping out!

Ludo’.

Re: [PATCH] Quick-start guide

[yoosty]

[-- Attachment #1: Type: text/plain, Size: 2796 bytes --]

Yes, I would say it is a bit redundant, partially on purpose :)

I wanted to create a short set of instructions to help users get in to a
GuixSD installation quickly, with the intent that they can poke around
inside the system and then read through the "System Installation" section
for more in-depth information.

Why? I was looking for one myself and couldn't find it ;) I've seen one or
two users in IRC who might benefit as well.

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

On Wed, Jun 8, 2016 at 5:47 AM, Ludovic Courtès <ludo@gnu.org> wrote:

> Hello!
>
> yoosty@gmail.com skribis:
>
> > +@node Quick Setup
> > +@section Quick Setup
> > +
> > +So you just want the quick-and-dirty guide? Assuming you have some
> > familiarity
> > +with GNU/Linux systems in general and have installed one several times
> > before
> > +you can probably get started with a few notes while citing
> > +@pxref{GNU Distribution} as necessary. As this is a quick-setup guide
> > we'll use
> > +some example defaults.
> > +
> > +The general idea is that you will:
> > +@itemize
> > +@item @uref{https://gnu.org/software/guix/download/, Download} the USB
> > installer
> > +@item Transfer the image to a USB stick (@pxref{USB Stick Installation})
> > +using dd
> > +@item Boot the USB stick
> > +@item Configure @pxref{Preparing for Installation,Networking}
> > +@item Set your @xref{Preparing for Installation,Disk Partitioning}
> > +(using an msdos label instead of a gpt label might be easier at the
> moment)
> > +@item Mount your partitions (e.g. /mnt)
> > +@item Run (again, e.g. /mnt) @command{herd start cow-store /mnt}
> > +@item Create a system configuration file using
> > +@xref{Proceeding with the Installation} and
> > +@xref{Using the Configuration System} as guides. It is suggested to
> start
> > +with the bare-bones template as you can easily re-configure your system
> > +once it is up.
> > +@item Using /mnt/root/guix_configs/config00.scm as the example config
> file
> > +and /mnt as the example install mount point, run
> > +@command{guix system init /mnt/root/guix_configs/config00.scm /mnt}
> > +@item Cross your fingers and grab a beer
> > +@item If you're using reasonably new hardware and a bare-bones config
> > +then guix should be done before your beverage and you can run
> > +@command{reboot}
> > +@end itemize
>
> [...]
>
> At first sight this seems redundant with the “System Installation”
> section, no?
>
> What shortcoming are you trying to address?
>
> Thanks for helping out!
>
> Ludo’.
>



-- 

   .:Justin:.

[-- Attachment #2: Type: text/html, Size: 3619 bytes --]

Re: [PATCH] Quick-start guide

[Leo Famulari]

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

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.

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.

So, please tell us of any specific shortcomings! It seems that you would
prefer "System Installation" to begin with an outline?

Re: [PATCH] Quick-start guide

[myglc2]

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.

Re: [PATCH] Quick-start guide

[Ludovic Courtès]

Hi!

myglc2 <myglc2@gmail.com> skribis:

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

Woow, that’s a lot of room for progress.  :-)

I think all of these issues need to be clarified and addressed.

The problem for me as a maintainer is that we don’t have a test suite
for the manual.  So I cannot simply apply a big patch and run “make
check” to ensure that nothing “broke” in the manual.  So I’m both
receptive and demanding here ;-), because it’s often the case that
editing the manual is more work than adding a couple of paragraphs here
and there.

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

Sure, my concern is about the duplication of information and additional
maintenance burden that ensues.

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

That sounds like a good idea.  To begin with, would you like to propose
a “Guix Quick Start” section that we could put between the “Features”
and “Invoking ‘guix package’” sections?

Thanks,
Ludo’.

Re: [PATCH] Quick-start guide

[yoosty]

[-- Attachment #1: Type: text/plain, Size: 2043 bytes --]

On Sat, Jun 11, 2016 at 10:49 AM, Leo Famulari <leo@famulari.name> wrote:

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

I agree on the 3rd party wikis point as well, hence my willing to pick up
some Texinfo and attempt submitting a patch :)


>
> So, please tell us of any specific shortcomings! It seems that you would
> prefer "System Installation" to begin with an outline?
>

Now that you mention it.. Merging what I've done in to the "System
Installation" section would make more sense location-wise but..

After reading the feedback here and spending some more time in IRC (which
really drives home the feedback about translations and colloquialisms,
thanks John) I would like to do the following:
- Add a contiguous set of examples to the existing "System Installation"
section (such that if you follow the examples you will almost certainly end
up with a working system, even if you don't read much of anything else)
- Add at least one more sub-section to "System Installation" that
introduces users to extending/customizing the initial system's .scm file
-- Something like a "Where to go from here? Customizing your installation."
-- A chance to tease users in to Scheme programming

Sound better?

-- 

   .:Justin:.

[-- Attachment #2: Type: text/html, Size: 3133 bytes --]

Re: [PATCH] Quick-start guide

[Ludovic Courtès]

Hi,

yoosty@gmail.com skribis:

> After reading the feedback here and spending some more time in IRC (which
> really drives home the feedback about translations and colloquialisms,
> thanks John) I would like to do the following:
> - Add a contiguous set of examples to the existing "System Installation"
> section (such that if you follow the examples you will almost certainly end
> up with a working system, even if you don't read much of anything else)

You mean OS config examples?  Currently there are 3 example
configurations.  We could add more, but I wonder if that wouldn’t be too
much for the manual itself (we could still add more to the installation
image, though.)

> - Add at least one more sub-section to "System Installation" that
> introduces users to extending/customizing the initial system's .scm file
> -- Something like a "Where to go from here? Customizing your installation."
> -- A chance to tease users in to Scheme programming

Makes sense.  The “Using the Configuration System” section was intended
to achieve this, but maybe it’s failing.  Do you think it could be
improved, or is a new section needed, and if so, how should we
articulate both?

Thanks,
Ludo’.

Re: [PATCH] Quick-start guide

[yoosty]

[-- Attachment #1: Type: text/plain, Size: 2401 bytes --]

On Thu, Jun 16, 2016 at 3:51 AM, Ludovic Courtès <ludo@gnu.org> wrote:

> Hi,
>
> yoosty@gmail.com skribis:
>
> > After reading the feedback here and spending some more time in IRC (which
> > really drives home the feedback about translations and colloquialisms,
> > thanks John) I would like to do the following:
> > - Add a contiguous set of examples to the existing "System Installation"
> > section (such that if you follow the examples you will almost certainly
> end
> > up with a working system, even if you don't read much of anything else)
>
> You mean OS config examples?  Currently there are 3 example
> configurations.  We could add more, but I wonder if that wouldn’t be too
> much for the manual itself (we could still add more to the installation
> image, though.)
>

> > - Add at least one more sub-section to "System Installation" that
> > introduces users to extending/customizing the initial system's .scm file
> > -- Something like a "Where to go from here? Customizing your
> installation."
> > -- A chance to tease users in to Scheme programming
>
> Makes sense.  The “Using the Configuration System” section was intended
> to achieve this, but maybe it’s failing.  Do you think it could be
> improved, or is a new section needed, and if so, how should we
> articulate both?
>

I might be viewing this from the wrong angle.. Maybe what's needed is not
necessarily different instructions, but more pointers to the existing
instructions :)

Can we put some comments in the current example configs to point to existing
documentation?

e.g.:

diff --git a/gnu/system/examples/bare-bones.tmpl
b/gnu/system/examples/bare-bones.tmpl
index 87e8d1e..811a6c3 100644
--- a/gnu/system/examples/bare-bones.tmpl
+++ b/gnu/system/examples/bare-bones.tmpl
@@ -38,6 +38,8 @@
                %base-user-accounts))

   ;; Globally-installed packages.
+  ;; See the "System Configuration"/"Globally-Visible Packages"
+  ;; section in the Guix manual for more info
   (packages (cons tcpdump %base-packages))

   ;; Add services to the baseline: a DHCP client and



Something else I'm probably just missing.. Is there a way to enumerate
%base-packages from the command line? I've seen you (Ludo) do this a few
times in the videos but I don't recall a mention of instructions for
configuring
this setup.

 --

   .:Justin:.

[-- Attachment #2: Type: text/html, Size: 3555 bytes --]

Re: [PATCH] Quick-start guide

[Ludovic Courtès]

yoosty@gmail.com skribis:

> On Thu, Jun 16, 2016 at 3:51 AM, Ludovic Courtès <ludo@gnu.org> wrote:
>
>> Hi,
>>
>> yoosty@gmail.com skribis:

[...]

>> > - Add at least one more sub-section to "System Installation" that
>> > introduces users to extending/customizing the initial system's .scm file
>> > -- Something like a "Where to go from here? Customizing your
>> installation."
>> > -- A chance to tease users in to Scheme programming
>>
>> Makes sense.  The “Using the Configuration System” section was intended
>> to achieve this, but maybe it’s failing.  Do you think it could be
>> improved, or is a new section needed, and if so, how should we
>> articulate both?
>>
>
> I might be viewing this from the wrong angle.. Maybe what's needed is not
> necessarily different instructions, but more pointers to the existing
> instructions :)

Maybe!  If you have ideas of what pointers to put where, that’s even
better.  :-)

> Can we put some comments in the current example configs to point to existing
> documentation?
>
> e.g.:
>
> diff --git a/gnu/system/examples/bare-bones.tmpl
> b/gnu/system/examples/bare-bones.tmpl
> index 87e8d1e..811a6c3 100644
> --- a/gnu/system/examples/bare-bones.tmpl
> +++ b/gnu/system/examples/bare-bones.tmpl
> @@ -38,6 +38,8 @@
>                 %base-user-accounts))
>
>    ;; Globally-installed packages.
> +  ;; See the "System Configuration"/"Globally-Visible Packages"
> +  ;; section in the Guix manual for more info
>    (packages (cons tcpdump %base-packages))

The problem is that these files are included in the manual, so it would
seem awkward IMO to give the section name here.  Not sure what to do
here.

> Something else I'm probably just missing.. Is there a way to enumerate
> %base-packages from the command line? I've seen you (Ludo) do this a few
> times in the videos but I don't recall a mention of instructions for
> configuring
> this setup.

This can be done from a Guile “read-eval-print loop” (REPL):

--8<---------------cut here---------------start------------->8---
$ guile
GNU Guile 2.0.11.156-c3f95-dirty
Copyright (C) 1995-2016 Free Software Foundation, Inc.

Guile comes with ABSOLUTELY NO WARRANTY; for details type `,show w'.
This program is free software, and you are welcome to redistribute it
under certain conditions; type `,show c' for details.

Enter `,help' for help.
scheme@(guile-user)> ,use(gnu)
scheme@(guile-user)> %base-packages
$1 = (#<package procps-3.2.8 gnu/packages/linux.scm:457 3830e40> #<package psmisc-22.20 gnu/packages/linux.scm:368 3eeb000> #<package which-2.21 gnu/packages/base.scm:683 37b8600> #<package less-451 gnu/packages/less.scm:27 36f0e40> #<package zile-2.4.11 gnu/packages/zile.scm:33 37b8180> #<package nano-2.4.2 gnu/packages/nano.scm:28 39f13c0> #<package dmd-0.2.01 gnu/packages/admin.scm:65 39d7cc0> #<package guix-0.8.3.5d09263 gnu/packages/package-management.scm:180 37b83c0> #<package lsof-4.88 gnu/packages/lsof.scm:30 37b80c0> #<package pciutils-3.2.0 gnu/packages/pciutils.scm:29 300e000> #<package usbutils-006 gnu/packages/linux.scm:524 3830d80> #<package util-linux-2.25.2 gnu/packages/linux.scm:391 3830f00> #<package inetutils-1.9.4 gnu/packages/admin.scm:168 39d79c0> #<package isc-dhcp-4.3.1 gnu/packages/admin.scm:391 39d7540> #<package iw-3.17 gnu/packages/linux.scm:1137 38300c0> #<package wireless-tools-30.pre9 gnu/packages/linux.scm:1705 3881540> #<package net-tools-1.60 gnu/packages/linux.scm:927 38303c0> #<package man-db-2.7.1 gnu/packages/man.scm:58 36f0c00> #<package sudo-1.8.10p3 gnu/packages/admin.scm:647 39d70c0> #<package kmod-17 gnu/packages/linux.scm:1528 3881780> #<package eudev-2.1.1 gnu/packages/linux.scm:1573 38816c0> #<package e2fsprogs-1.42.13 gnu/packages/linux.scm:548 3830cc0> #<package kbd-2.0.2 gnu/packages/linux.scm:1450 3881900> #<package bash-completion-2.1 gnu/packages/bash.scm:243 3260540> #<package guile-2.0.11 gnu/packages/bootstrap.scm:145 3f8ed80> #<package bash-4.3.39 gnu/packages/bootstrap.scm:145 3f8ef00> #<package coreutils-8.24 gnu/packages/bootstrap.scm:145 3f8e900> #<package findutils-4.4.2 gnu/packages/bootstrap.scm:145 3f919c0> #<package grep-2.21 gnu/packages/bootstrap.scm:145 3f8e780> #<package sed-4.2.2 gnu/packages/bootstrap.scm:145 3f91b40> #<package diffutils-3.3 gnu/packages/bootstrap.scm:145 3f91e40> #<package patch-2.7.5 gnu/packages/bootstrap.scm:145 3f91cc0> #<package gawk-4.1.3 gnu/packages/bootstrap.scm:145 3f91840> #<package tar-1.28 gnu/packages/bootstrap.scm:145 3f8e600> #<package gzip-1.6 gnu/packages/bootstrap.scm:145 3f8e480> #<package bzip2-1.0.6 gnu/packages/bootstrap.scm:145 3f8e300> #<package xz-5.0.4 gnu/packages/bootstrap.scm:145 3f8e180> #<package lzip-1.16 gnu/packages/compression.scm:301 3054000>)
--8<---------------cut here---------------end--------------->8---

Or as a one-liner:

--8<---------------cut here---------------start------------->8---
$ guile -c '(use-modules (gnu) (guix)) (pk (map package-full-name %base-packages))'

;;; (("procps-3.2.8" "psmisc-22.20" "which-2.21" "less-451" "zile-2.4.11" "nano-2.4.2" "dmd-0.2.01" "guix-0.8.3.5d09263" "lsof-4.88" "pciutils-3.2.0" "usbutils-006" "util-linux-2.25.2" "inetutils-1.9.4" "isc-dhcp-4.3.1" "iw-3.17" "wireless-tools-30.pre9" "net-tools-1.60" "man-db-2.7.1" "sudo-1.8.10p3" "kmod-17" "eudev-2.1.1" "e2fsprogs-1.42.13" "kbd-2.0.2" "bash-completion-2.1" "guile-2.0.11" "bash-4.3.39" "coreutils-8.24" "findutils-4.4.2" "grep-2.21" "sed-4.2.2" "diffutils-3.3" "patch-2.7.5" "gawk-4.1.3" "tar-1.28" "gzip-1.6" "bzip2-1.0.6" "xz-5.0.4" "lzip-1.16"))
--8<---------------cut here---------------end--------------->8---

HTH!

Ludo’.

Re: [PATCH] Quick-start guide

[John Darrington]

[-- Attachment #1: Type: text/plain, Size: 6550 bytes --]

On Sat, Jun 04, 2016 at 01:00:17PM -0700, yoosty@gmail.com wrote:
     Howdy!
     
     This is my first submission, please be gentle ;)
     
     Input is definitely welcome.


     diff --git a/doc/contributing.texi b/doc/contributing.texi
     index 208c6af..46c652f 100644
     --- a/doc/contributing.texi
     +++ b/doc/contributing.texi
     @@ -18,6 +18,7 @@ the @file{CODE-OF-CONDUCT} file in the source tree.
      @menu
      * Building from Git::           The latest and greatest.
      * Running Guix Before It Is Installed::  Hacker tricks.
     +* Quick Setup::                 The quick and easy tools
      * The Perfect Setup::           The right tools.
      * Coding Style::                Hygiene of the contributor.
      * Submitting Patches::          Share your work.
     @@ -153,6 +154,75 @@ the @file{/root/.config/guix/latest} symlink to point
     to
      @command{guix} as your user does.}
     
     
     +@node Quick Setup
     +@section Quick Setup
     +
     +So you just want the quick-and-dirty guide? Assuming you have some
     familiarity
     +with GNU/Linux systems in general and have installed one several times
     before
     +you can probably get started with a few notes while citing
     +@pxref{GNU Distribution} as necessary. As this is a quick-setup guide
     we'll use
     +some example defaults.
     +The general idea is that you will:

What is the purpose of the above paragraph?  It does not convey any information
to the reader.  Whilst  I think it is good to put the reader at ease, this is 
overdoing it.  Further, it is vague and overly conditional ("Assuming you have ...
you can probably ...") which will make the reader feel unsure of himself.  
I would replace these three sentances by something short and to the point such 
as "Setting up Guix involves the following steps:"

     +@itemize
     +@item @uref{https://gnu.org/software/guix/download/, Download} the USB
     installer
     +@item Transfer the image to a USB stick (@pxref{USB Stick Installation})
     +using dd
     +@item Boot the USB stick
     +@item Configure @pxref{Preparing for Installation,Networking}
     +@item Set your @xref{Preparing for Installation,Disk Partitioning}
     +(using an msdos label instead of a gpt label might be easier at the moment)
     +@item Mount your partitions (e.g. /mnt)
     +@item Run (again, e.g. /mnt) @command{herd start cow-store /mnt}
     +@item Create a system configuration file using
     +@xref{Proceeding with the Installation} and
     +@xref{Using the Configuration System} as guides. It is suggested to start
     +with the bare-bones template as you can easily re-configure your system
     +once it is up.
     +@item Using /mnt/root/guix_configs/config00.scm as the example config file
     +and /mnt as the example install mount point, run
     +@command{guix system init /mnt/root/guix_configs/config00.scm /mnt}
     +@item Cross your fingers and grab a beer
     +@item If you're using reasonably new hardware and a bare-bones config

What do you mean by "bare-bones config" and what if the reader is not using one?
or not using new hardware?

     +then guix should be done before your beverage and you can run

Else where you have written "Guix" rather than "guix".

     +@command{reboot}
     +@end itemize
     +

     +Now you should be ready to rock! 

I recommend that you avoid cliches like this.  Readers for whom English is a 
second language, may not be familiar with such expressions. It might confuse 
them.  Similarly, with "cross your fingers and grab a beer".  Instead, be 
specific and say something like: "Installation will now proceed.  It will take
several minutes. If you are using older hardware, then it may take somewhat 
longer".  And importantly, say what the user should see after the process has 
completed.

     + Don't forget to set your user passwords.

How should the reader do that?
     +
     +Of course, you're not here just to have a working system are you, you want

Punctuation.  Should read: "... are you?  You want..."

     +to dive in to the source, right? Let's take a quick look at that as well.

Again, expressions like "to dive in" might confuse some readers.

     +This guide assumes that you have at least perused @pxref{Building from
     Git}.

     +First you might want to head to
     +@uref{http://git.savannah.gnu.org/cgit/guix.git, the Guix Git page} and
     browse
     +around. We're going to assume that you utilized a bare-bones config as per
     the
Who is "we" ?  Again, what if he didn't use a "bare-bones config"?

     +quick install guide above. In this short example you will be shown simply
     +how to change the release version of Guix (not something you will likely do
     +but an easy and fun example).
     +
     +@itemize
     +@item Install git in to your user's profile: @command{guix package
     --install git}
     +@item Create a directory for your git checkout (e.g. @command{mkdir
     ~/git_repos})
     +@item Clone the Guix repository:
     +@command{cd ~/git_repos/; git clone git://git.sv.gnu.org/guix.git; cd guix}
     +@item To make the simple version change:
     +@code{AC_INIT([GNU Guix], [0.10.0], [bug-guix@@gnu.org], [guix],}
     +to
     +@code{AC_INIT([GNU Guix], [0.10.42], [bug-guix@@gnu.org], [guix],}
     +@item Check your change with: @command{git diff configure.ac}
     +@item Let Guix set up your Guix build
     +environment:@command{guix environment guix}
     +@item Build Guix:
     +@command{./bootstrap ; ./configure --localstatedir=/var ; make}
     +@item Run the daemon in a pre-installation environment:
     +@command{sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild}
     +@item Switch to a new terminal
     +@item Check the pre-installation environement daemon's version:
     +@command{./git_repos/guix/pre-inst-env guix --version}

     +@item Your version output should be updated!
This sentance is not a part of the procedure.  It should appear outside of the
@itemize block

     +@end itemize
     +
     +
      @node The Perfect Setup
      @section The Perfect Setup
     
     
     -- 
     
        .:Justin:.

-- 
Avoid eavesdropping.  Send strong encryted email.
PGP Public key ID: 1024D/2DE827B3 
fingerprint = 8797 A26D 0854 2EAB 0285  A290 8A67 719C 2DE8 27B3
See http://sks-keyservers.net or any PGP keyserver for public key.


[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 181 bytes --]