Re: Some things to be aware of for docs

[Leo Famulari <leo@famulari.name>]

On Mon, Feb 15, 2016 at 02:33:47PM -0500, Esteban Enrique wrote:
> I am a relative newcomer to GNU/Linux (4 years around) and I have been
> wanting to use GuixSD for the past weeks but I have been having trouble. I
> think this is due to unclear documents for beginners (like myself).

Thanks for trying, and I'm sorry it hasn't worked yet!

> 
>  First, formatting the drive. I have some experience with Arch Linux, so I
> had a general sense  of how to use fdisk. However, for the vast majority of
> those who don't know about this, there could be a link or a self-contained
> explanation that goes through the process of formatting the disk.

Personally, I feel a tension between improving the fdisk manual so that
beginners can use it and just giving step-by-step instructions in our
manual.

I really don't like Arch's approach of working around poor upstream
manuals by giving step-by-step instructions in their wiki, because it
only helps Arch users [0]. If the fdisk manual is insufficient, we
should help them improve it.

On the other hand, in the meantime, *our* potential users are struggling
to get started.

I _do_ think it's valuable to provide instructions on using 3rd party
software when it relates to quirks in our use of said software. For
example, I wrote a section in our manual about using QEMU with our `guix
system vm-image` command.

What do people think?

> 
> Next, (I think this has been in the works, but I am not sure) there needs to
> be a reminder to run the command 'guix pull' before installation to avoid
> any problems.

The current version of the manual does mention this at certain points.
Can you look at it and tell us where it's missing so we can add it? I
know this is important to new users.

FYI, you can build HTML pages of the current version of the manual from
a git checkout like this:
$ make doc/guix.html

> 
> Finally, there could be a quick note which explains the slow download and
> installation from hydra.

This is really a temporary situation that should start to improve in the
coming weeks. Perhaps we should add a note to the #guix banner.

> 
> Overall, the documentation needs work, and I have yet to successfully
> install GuixSD. I will be trying again soon and reporting problems /from an
> experienced beginner's perspective/. This will hopefully make the project
> more beginner friendly. (Note I do not use the term user-friendly (I hate
> the term), because it does not need to be user-friendly, just welcoming to
> those that are willing to take the time to learn what is up).

Some of us are willing to spend *a lot* of time helping individual users
get started. Please bug us on #guix or the help-guix mailing list with
your specific problems :) We want to know your problems so we can
improve the manual!

> 
> There are more things that need help, but those are the ones I saw lacking
> most. How often are the docs updated by the way?

Constantly, but the web-based version is not. I just opened a bug about
this.

[0] I know that in practice users of other distros refer to the Arch
wiki.