Re: feedback as solicited by Guix manual (Section 7.1.5)

[Matthew Jordan]

I just looked ouver the installation part of the manual.

> What parts do you think should be added to our manual? A number of these
> steps are already covered in section 7.1 System Installation.

That was mostly a copy paste from my notes.  But what I wouldn't mind
seeing in the manual is as follows;

1. Section 7.1.4.2 Networking;

mentions using ifconfig, correct me if I"m wrong but isn't ifconfig
considered deprecated?

In which case iproute2 commands could be used;

$ ip link show
$ ip link set ens3 up

2. Section 7.1.4.3 Disk Partitioning

It would be nice to indicate that you may need additional swap space to
build the various packages that come with the install.  Also sufficient
space under /tmp is needed. In my case I had to bind mount the my tmp
partition from the install target, and turn on the swap to achieve a
successful install. I used these commands to achieve that.

$ mount --bind /mnt/tmp /tmp
$ swapon /dev/sda3

> Personally, I don't like putting instructions on how to use 3rd party
> software in manuals such as ours (or the Gentoo or Arch manuals) unless
> the information is very specific to how we use the software.
>
> In my opinion, if there is some deficiency with the 3rd party programs'
> documentation, that documentation should be improved.
>
> Otherwise, knowledge is fragmented into a variety of places where it
> probably won't be updated as the 3rd party software changes. Also, each
> system's manual or wiki will invariably contain some info that is
> specific to that system but not declared as such. And the new, external
> documentation will probably not be reviewed by the upstream maintainers
> for correctness, spreading bad advice across the internet.  Finally, the
> upstream manual will *still* not be improved.
>
> On the other hand, we should strive to make our system as easy to
> install as possible. So, specific advice is most welcome! :)

While these are valid points, and I have to say I agree with them. Even
Gentoo and Arch (which are among some of the more challenging distros),
do provide some example/recipe to assist with partitioning.  I'm not
saying we quote someone's manual, but someone might find it useful.

We could always indicate that one should refer to upstream manual for
the latest info, and still provide some steps based on a partitioning
plan. I think this would be very helpful to those who may not be fully
verse in partitioning.  My first time using Gentoo was pretty decent
because of the documentation provided. Here is the appropriate snippet
from my notes;

Paritioning plan
Assumming disk is 20GiB
Bootloader 2MiB
/boot 300MiB ext2/4
Swap 1GiB
/ (rest of disk space) ext4

$ lsblk
Start parted shell
$ parted -a optimal /dev/sda
(parted) unit MiB
(parted) mklabel gpt
(parted) mkpart primary 1MiB 3MiB
(parted) name 1 grub
(parted) set 1 bios_grub on
(parted) print
(parted) mkpart primary 3MiB 303MiB
(parted) name 2 boot
(parted) print

Calculation on host with zsh shell
$ ((mib = 1 * (1024 ** 1)))
$ print ${mib}
1024
$ print $((mib + 303))
1327

(parted) mkpart primary 303MiB 1327MiB
(parted) name 3 swap
(parted) print
(parted) mkpart primary 1327MiB -1
(parted) name 4 root
(parted) set 2 boot on
(parted) print
(parted) quit

Of course feel free free to accept/reject these ideas, as they are just
suggestions based on my state understanding when I first discovered Guix &
GuixSD.  I like to think of Guix as the next evolution of Linux from
Arch Linux or Gentoo Linux ^_^.

Respectfully,

-- 
Matthew Jordan
Sent with my mu4e

Leo Famulari writes:

> On Tue, May 31, 2016 at 12:31:16PM -0400, Matthew Jordan wrote:
>> What follows are the steps I took to setup my GuixSD box.  What I'm
>> wondering is how would I go about contributing this in some way to the
>> documentation? With some modification of course.
>
> What parts do you think should be added to our manual? A number of these
> steps are already covered in section 7.1 System Installation.
>
>> I am just presenting this cause I had to look around a lot, such as the
>> Gentoo Installation Manual, and Arch Linux manuals in addition to the
>> Parted and Guix Manuals when I attempted my first install.  Just thought
>> it would be a good idea to perhaps have some solid example/steps in the
>> Guix Manual for the installation.
>
> Personally, I don't like putting instructions on how to use 3rd party
> software in manuals such as ours (or the Gentoo or Arch manuals) unless
> the information is very specific to how we use the software.
>
> In my opinion, if there is some deficiency with the 3rd party programs'
> documentation, that documentation should be improved.
>
> Otherwise, knowledge is fragmented into a variety of places where it
> probably won't be updated as the 3rd party software changes. Also, each
> system's manual or wiki will invariably contain some info that is
> specific to that system but not declared as such. And the new, external
> documentation will probably not be reviewed by the upstream maintainers
> for correctness, spreading bad advice across the internet.  Finally, the
> upstream manual will *still* not be improved.
>
> On the other hand, we should strive to make our system as easy to
> install as possible. So, specific advice is most welcome! :)