Re: Some things to be aware of for docs

[ludo@gnu.org (Ludovic Courtès)]

Esteban Enrique <esteban.enrique.97@gmail.com> skribis:

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

There have been improvements in this regard recently:
<http://git.savannah.gnu.org/cgit/guix.git/tree/doc/guix.texi#n5757>.

But I definitely sympathize with Leo’s comment: I’d rather include links
to actual fdisk documentation than duplicate it.

A lot of the OS builds on GNU packages, which is often nicely documented
and cross-referenceable (for instance, Parted.)  But documentation of
non-GNU software is less convenient to cross-reference (for instance,
the fdisk implementation of util-linux.)

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

There’s a reminder, but it’s easily overlooked.  ;-)  Anyway, it’s a bug
that should be fixed so the reminder isn’t even necessary.

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

It’s tricky, because we don’t want to “write in the stone” that we have
a slow server.  ;-)  Hopefully this will be addressed soon by switching
to a newer machine and/or mirroring things.

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

Docs are updated when new features are added or when people notice
things that need to be improved.

Thanks for the valuable feedback!

Ludo’.