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

[Leo Famulari]

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! :)