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.
