From mboxrd@z Thu Jan 1 00:00:00 1970 From: Esteban Enrique Subject: Some things to be aware of for docs Date: Mon, 15 Feb 2016 14:33:47 -0500 Message-ID: <56C2281B.90104@gmail.com> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="------------090206090002030902000507" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:36240) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVOu5-0000P0-Tc for help-guix@gnu.org; Mon, 15 Feb 2016 14:33:50 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aVOu4-0005wk-Q7 for help-guix@gnu.org; Mon, 15 Feb 2016 14:33:49 -0500 Received: from mail-qg0-x233.google.com ([2607:f8b0:400d:c04::233]:33690) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVOu4-0005wg-Kc for help-guix@gnu.org; Mon, 15 Feb 2016 14:33:48 -0500 Received: by mail-qg0-x233.google.com with SMTP id b35so117424868qge.0 for ; Mon, 15 Feb 2016 11:33:48 -0800 (PST) Received: from ?IPv6:2601:182:c401:11b7:bddd:9d60:eef1:62f? ([2601:182:c401:11b7:bddd:9d60:eef1:62f]) by smtp.gmail.com with ESMTPSA id t187sm11558730qht.39.2016.02.15.11.33.47 for (version=TLSv1/SSLv3 cipher=OTHER); Mon, 15 Feb 2016 11:33:47 -0800 (PST) List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org Sender: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org To: help-guix@gnu.org This is a multi-part message in MIME format. --------------090206090002030902000507 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit 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. 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. Finally, there could be a quick note which explains the slow download and installation from hydra. 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). 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? --------------090206090002030902000507 Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: 8bit 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.

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.

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

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

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?


--------------090206090002030902000507-- From mboxrd@z Thu Jan 1 00:00:00 1970 From: Leo Famulari Subject: Re: Some things to be aware of for docs Date: Mon, 15 Feb 2016 17:00:44 -0500 Message-ID: <20160215220044.GB22646@jasmine> References: <56C2281B.90104@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:40174) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVRCD-0004XC-4o for help-guix@gnu.org; Mon, 15 Feb 2016 17:00:42 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aVRC9-0004py-TX for help-guix@gnu.org; Mon, 15 Feb 2016 17:00:41 -0500 Received: from out2-smtp.messagingengine.com ([66.111.4.26]:60890) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVRC9-0004pu-Q6 for help-guix@gnu.org; Mon, 15 Feb 2016 17:00:37 -0500 Content-Disposition: inline In-Reply-To: <56C2281B.90104@gmail.com> List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org Sender: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org To: Esteban Enrique Cc: help-guix@gnu.org 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. From mboxrd@z Thu Jan 1 00:00:00 1970 From: Esteban Enrique Subject: Re: Some things to be aware of for docs Date: Mon, 15 Feb 2016 17:51:27 -0500 Message-ID: <56C2566F.209@gmail.com> References: <56C2281B.90104@gmail.com> <20160215220044.GB22646@jasmine> Mime-Version: 1.0 Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:53814) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVRzO-00047E-4G for help-guix@gnu.org; Mon, 15 Feb 2016 17:51:31 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aVRzN-00082O-2J for help-guix@gnu.org; Mon, 15 Feb 2016 17:51:30 -0500 Received: from mail-qg0-x231.google.com ([2607:f8b0:400d:c04::231]:32912) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVRzM-00082J-UJ for help-guix@gnu.org; Mon, 15 Feb 2016 17:51:29 -0500 Received: by mail-qg0-x231.google.com with SMTP id b35so120736558qge.0 for ; Mon, 15 Feb 2016 14:51:28 -0800 (PST) In-Reply-To: <20160215220044.GB22646@jasmine> List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org Sender: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org To: Leo Famulari Cc: help-guix@gnu.org On 02/15/2016 05:00 PM, Leo Famulari wrote: > 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? Okay, so this is what RMS means when he encourages writing/editing documentation for the GNU project as a primary way to help these days. There exists documentation but it is poorly written for the aspiring beginner. The whole documentation situation is very bad on so many programs, it is not just you guys. I think it might stem from the fact that the developers of programs are so knowledgeable about their program that it is difficult to write in a way that welcomes new users rather than scare them away. For example, I have been learning emacs lately and the documentation there is top notch, very clearly written, for example. So yes, I agree with your disdain for the Arch way of creating documentation for 3rd party programs. I have always found their information helpful, and I frequently visit their site because it is so well documented. I have never written documentation or even edited or proofread or suggested anything, so this is something I would be willing to get practiced at and help doing for GuixSD. Also, as a part of the GNU project, I agree that our community should work on GNU documentation rather than create our own. > 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 Sure. In 7.1.4, probably in the beginning, 'guix pull,' as that is the advice I got from the IRC channel (which is great and very active! > 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! Yes, I have been frequenting #guix for a while now and it sure is helpful. From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nils Gillmann Subject: Re: Some things to be aware of for docs Date: Tue, 16 Feb 2016 00:54:34 +0100 Message-ID: <87si0ta5s5.fsf@grrlz.net> References: <56C2281B.90104@gmail.com> <20160215220044.GB22646@jasmine> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:39788) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVSyW-00029I-DN for help-guix@gnu.org; Mon, 15 Feb 2016 18:54:41 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aVSyT-0005K5-75 for help-guix@gnu.org; Mon, 15 Feb 2016 18:54:40 -0500 Received: from latitanza.investici.org ([82.94.249.234]:52975) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVSyS-0005Js-UK for help-guix@gnu.org; Mon, 15 Feb 2016 18:54:37 -0500 In-Reply-To: <20160215220044.GB22646@jasmine> (Leo Famulari's message of "Mon, 15 Feb 2016 17:00:44 -0500") List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org Sender: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org To: Leo Famulari Cc: help-guix@gnu.org Leo Famulari writes: > On Mon, Feb 15, 2016 at 02:33:47PM -0500, Esteban Enrique wrote: >> >> 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? > --snip-- > > [0] I know that in practice users of other distros refer to the Arch > wiki. I would refer to gentoo wiki section handbook, subsection formating the disks (or smth like that) for this as it's very understandable for inexperienced user in my opinion. But that's just me, where I already had 14+ years of experience when I read it 1 or 2 years ago. Gentoo documentation is overall very good (the wiki section) and gets the balance right. I think something similar to this is a nice approach. Documentation is something most people don't do good enough, and as long as the upstream docs aren't good, it would be good to have something in one place to refer to. -- ng From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nils Gillmann Subject: Re: Some things to be aware of for docs Date: Tue, 16 Feb 2016 01:00:14 +0100 Message-ID: <87oabha5ip.fsf@grrlz.net> References: <56C2281B.90104@gmail.com> <20160215220044.GB22646@jasmine> <56C2566F.209@gmail.com> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:40861) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVT3z-0002rC-Ak for help-guix@gnu.org; Mon, 15 Feb 2016 19:00:20 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aVT3w-0006dh-3L for help-guix@gnu.org; Mon, 15 Feb 2016 19:00:19 -0500 Received: from latitanza.investici.org ([82.94.249.234]:60931) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVT3v-0006db-QD for help-guix@gnu.org; Mon, 15 Feb 2016 19:00:16 -0500 In-Reply-To: <56C2566F.209@gmail.com> (Esteban Enrique's message of "Mon, 15 Feb 2016 17:51:27 -0500") List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org Sender: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org To: Esteban Enrique Cc: help-guix@gnu.org Esteban Enrique writes: > On 02/15/2016 05:00 PM, Leo Famulari wrote: >> 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? > Okay, so this is what RMS means when he encourages writing/editing > documentation for the GNU project as a primary way to help these > days. There exists documentation but it is poorly written for the > aspiring beginner. The whole documentation situation is very bad on so > many programs, it is not just you guys. I think it might stem from the > fact that the developers of programs are so knowledgeable about their > program that it is difficult to write in a way that welcomes new users > rather than scare them away. > > For example, I have been learning emacs lately and the documentation > there is top notch, very clearly written, for example. > > So yes, I agree with your disdain for the Arch way of creating > documentation for 3rd party programs. I have always found their > information helpful, and I frequently visit their site because it is > so well documented. > > I have never written documentation or even edited or proofread or > suggested anything, so this is something I would be willing to get > practiced at and help doing for GuixSD. Also, as a part of the GNU > project, I agree that our community should work on GNU documentation > rather than create our own. But after reading this response of Esteban I agree with it more than with what I have written. Maybe the best way would be to provide temporary workaround to the documentation situation and also encourage users to help us with changing upstream documentation, so we can provide links to good, readable, understandable manual sections from an inexperienced users view. Maybe this could also be pointed out on the website / the manual. >> 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 > Sure. In 7.1.4, probably in the beginning, 'guix pull,' as that is the > advice I got from the IRC channel (which is great and very active! >> 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! > Yes, I have been frequenting #guix for a while now and it sure is helpful. > -- ng From mboxrd@z Thu Jan 1 00:00:00 1970 From: Leo Famulari Subject: Re: Some things to be aware of for docs Date: Mon, 15 Feb 2016 19:07:23 -0500 Message-ID: <20160216000723.GA27625@jasmine> References: <56C2281B.90104@gmail.com> <20160215220044.GB22646@jasmine> <87si0ta5s5.fsf@grrlz.net> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:42068) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVTAm-0003ZZ-Rt for help-guix@gnu.org; Mon, 15 Feb 2016 19:07:21 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aVTAj-0008Fi-K6 for help-guix@gnu.org; Mon, 15 Feb 2016 19:07:20 -0500 Received: from out2-smtp.messagingengine.com ([66.111.4.26]:57070) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVTAj-0008FR-BN for help-guix@gnu.org; Mon, 15 Feb 2016 19:07:17 -0500 Content-Disposition: inline In-Reply-To: <87si0ta5s5.fsf@grrlz.net> List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org Sender: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org To: Nils Gillmann Cc: help-guix@gnu.org On Tue, Feb 16, 2016 at 12:54:34AM +0100, Nils Gillmann wrote: > Leo Famulari writes: > > > On Mon, Feb 15, 2016 at 02:33:47PM -0500, Esteban Enrique wrote: > >> > >> 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? > > > --snip-- > > > > [0] I know that in practice users of other distros refer to the Arch > > wiki. > I would refer to gentoo wiki section handbook, subsection > formating the disks (or smth like that) for this as it's very > understandable for inexperienced user in my opinion. > But that's just me, where I already had 14+ years of experience > when I read it 1 or 2 years ago. Gentoo documentation is overall > very good (the wiki section) and gets the balance right. > > I think something similar to this is a nice approach. > Documentation is something most people don't do good > enough, and as long as the upstream docs aren't good, it would be > good to have something in one place to refer to. I suggest that if the docs of fdisk (for example) are insufficient, why not improve them directly, rather than creating some distro-specific list of instructions that will need to be manually kept in sync with updates to fdisk? Re-documenting fdisk in a distro's documentation is the wrong approach, in my opinion. From mboxrd@z Thu Jan 1 00:00:00 1970 From: myglc2 Subject: Re: Some things to be aware of for docs Date: Mon, 15 Feb 2016 17:28:05 -0500 Message-ID: <87twl94nii.fsf@gmail.com> References: <56C2281B.90104@gmail.com> <20160215220044.GB22646@jasmine> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:47933) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVRcW-0004WE-QT for help-guix@gnu.org; Mon, 15 Feb 2016 17:27:53 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aVRcR-0003CT-RH for help-guix@gnu.org; Mon, 15 Feb 2016 17:27:52 -0500 Received: from plane.gmane.org ([80.91.229.3]:39300) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVRcR-0003CB-Jf for help-guix@gnu.org; Mon, 15 Feb 2016 17:27:47 -0500 Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1aVRcP-00030v-AX for help-guix@gnu.org; Mon, 15 Feb 2016 23:27:45 +0100 Received: from c-73-167-118-254.hsd1.ma.comcast.net ([73.167.118.254]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 15 Feb 2016 23:27:45 +0100 Received: from myglc2 by c-73-167-118-254.hsd1.ma.comcast.net with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 15 Feb 2016 23:27:45 +0100 List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org Sender: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org To: help-guix@gnu.org Leo Famulari writes: > On Mon, Feb 15, 2016 at 02:33:47PM -0500, Esteban Enrique wrote: [...] >> 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. [...] > On the other hand, in the meantime, *our* potential users are struggling > to get started. [...] > What do people think? A user should be able to try GuixSD without knowing anything about partitioning. So, there should concrete and simple instructions (e.g. 1 DOS partition no swap) guaranteed to work on an actual hard drive. From mboxrd@z Thu Jan 1 00:00:00 1970 From: Esteban Enrique Subject: Re: Some things to be aware of for docs Date: Mon, 15 Feb 2016 21:06:35 -0500 Message-ID: References: <56C2281B.90104@gmail.com> <20160215220044.GB22646@jasmine> <87twl94nii.fsf@gmail.com> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=001a1144169e45296c052bd99531 Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:37337) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVV2D-0002fC-DD for help-guix@gnu.org; Mon, 15 Feb 2016 21:06:38 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aVV2C-0007a3-Aq for help-guix@gnu.org; Mon, 15 Feb 2016 21:06:37 -0500 Received: from mail-vk0-x231.google.com ([2607:f8b0:400c:c05::231]:35681) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aVV2C-0007Zi-5t for help-guix@gnu.org; Mon, 15 Feb 2016 21:06:36 -0500 Received: by mail-vk0-x231.google.com with SMTP id e6so121244793vkh.2 for ; Mon, 15 Feb 2016 18:06:36 -0800 (PST) In-Reply-To: <87twl94nii.fsf@gmail.com> List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org Sender: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org To: myglc2 Cc: help-guix@gnu.org --001a1144169e45296c052bd99531 Content-Type: text/plain; charset=UTF-8 Yes, and unfortunately it is far from concrete and simple at this point. It basically says 'the drive should be partitioned.' I think adding a quick step like you say should be sufficient without going into too much detail. It just a suggestion, or an example config. On Mon, Feb 15, 2016 at 5:28 PM, myglc2 wrote: > Leo Famulari writes: > > > On Mon, Feb 15, 2016 at 02:33:47PM -0500, Esteban Enrique wrote: > [...] > >> 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. > [...] > > On the other hand, in the meantime, *our* potential users are struggling > > to get started. > [...] > > What do people think? > > A user should be able to try GuixSD without knowing anything about > partitioning. So, there should concrete and simple instructions (e.g. 1 > DOS partition no swap) guaranteed to work on an actual hard drive. > > > --001a1144169e45296c052bd99531 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
Yes, and unfortunately it is far from concrete and simple = at this point. It basically says 'the drive should be partitioned.'= I think adding a quick step like you say should be sufficient without goin= g into too much detail. It just a suggestion, or an example config.

On Mon, Feb 15,= 2016 at 5:28 PM, myglc2 <myglc2@gmail.com> wrote:
Leo Famulari <leo@famulari.name> writes:

> On Mon, Feb 15, 2016 at 02:33:47PM -0500, Esteban Enrique wrote:
[...]
>>=C2=A0 First, formatting the drive. I have some ex= perience with Arch Linux, so I
>> had a general sense=C2=A0 of how to use fdisk. However, for the va= st majority of
>> those who don't know about this, there could be a link or a se= lf-contained
>> explanation that goes through the process of formatting the disk.<= br> [...]
> On the other hand, in the meantime, *our* potential u= sers are struggling
> to get started.
[...]
> What do people think?

A user should be able to try GuixSD without knowing anything about
partitioning.=C2=A0 So, there should concrete and simple instructions (e.g.= 1
DOS partition no swap) guaranteed to work on an actual hard drive.



--001a1144169e45296c052bd99531-- From mboxrd@z Thu Jan 1 00:00:00 1970 From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Subject: Re: Some things to be aware of for docs Date: Wed, 24 Feb 2016 22:26:04 +0100 Message-ID: <8737sher6b.fsf@gnu.org> References: <56C2281B.90104@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:58092) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aYgwm-0006Kq-3X for help-guix@gnu.org; Wed, 24 Feb 2016 16:26:13 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aYgwh-0002F2-4I for help-guix@gnu.org; Wed, 24 Feb 2016 16:26:12 -0500 In-Reply-To: <56C2281B.90104@gmail.com> (Esteban Enrique's message of "Mon, 15 Feb 2016 14:33:47 -0500") List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org Sender: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org To: Esteban Enrique Cc: help-guix@gnu.org Esteban Enrique 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: . But I definitely sympathize with Leo=E2=80=99s comment: I=E2=80=99d 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=E2=80=99s a reminder, but it=E2=80=99s easily overlooked. ;-) Anywa= y, it=E2=80=99s a bug that should be fixed so the reminder isn=E2=80=99t even necessary. > Finally, there could be a quick note which explains the slow download > and installation from hydra. It=E2=80=99s tricky, because we don=E2=80=99t want to =E2=80=9Cwrite in the= stone=E2=80=9D 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=E2=80=99. From mboxrd@z Thu Jan 1 00:00:00 1970 From: Andreas Enge Subject: Re: Some things to be aware of for docs Date: Wed, 24 Feb 2016 22:28:08 +0100 Message-ID: <20160224212808.GA5991@solar> References: <56C2281B.90104@gmail.com> <8737sher6b.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:58624) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aYgyo-0006i4-8M for help-guix@gnu.org; Wed, 24 Feb 2016 16:28:18 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aYgyj-00038f-A2 for help-guix@gnu.org; Wed, 24 Feb 2016 16:28:18 -0500 Received: from mailrelay1.public.one.com ([91.198.169.124]:38648) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aYgyi-00038T-V0 for help-guix@gnu.org; Wed, 24 Feb 2016 16:28:13 -0500 Content-Disposition: inline In-Reply-To: <8737sher6b.fsf@gnu.org> List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org Sender: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org To: Ludovic =?iso-8859-15?Q?Court=E8s?= Cc: Esteban Enrique , help-guix@gnu.org On Wed, Feb 24, 2016 at 10:26:04PM +0100, Ludovic Courtès wrote: > Esteban Enrique skribis: > > 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. One of the doc patches I just pushed has added this reminder. Andreas From mboxrd@z Thu Jan 1 00:00:00 1970 From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Subject: Re: Some things to be aware of for docs Date: Sat, 27 Feb 2016 18:27:32 +0100 Message-ID: <87bn72xdvf.fsf@gnu.org> References: <56C2281B.90104@gmail.com> <8737sher6b.fsf@gnu.org> <20160224212808.GA5991@solar> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:43218) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aZieZ-00085o-05 for help-guix@gnu.org; Sat, 27 Feb 2016 12:27:40 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aZieV-0001hJ-R1 for help-guix@gnu.org; Sat, 27 Feb 2016 12:27:38 -0500 In-Reply-To: <20160224212808.GA5991@solar> (Andreas Enge's message of "Wed, 24 Feb 2016 22:28:08 +0100") List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org Sender: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org To: Andreas Enge Cc: Esteban Enrique , help-guix@gnu.org Andreas Enge skribis: > On Wed, Feb 24, 2016 at 10:26:04PM +0100, Ludovic Court=C3=A8s wrote: >> Esteban Enrique skribis: >> > 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=E2=80=99s a reminder, but it=E2=80=99s easily overlooked. ;-) An= yway, it=E2=80=99s a bug >> that should be fixed so the reminder isn=E2=80=99t even necessary. > > One of the doc patches I just pushed has added this reminder. Really? I was referring to this bit from 2014: @quotation Note @c The paragraph below refers to the problem discussed at @c . It is highly recommended to run @command{guix pull} once before you run @command{guix system reconfigure} for the first time (@pxref{Invoking guix pull}). Failing to do that you would see an older version of Guix once @command{reconfigure} has completed. @end quotation Ludo=E2=80=99. From mboxrd@z Thu Jan 1 00:00:00 1970 From: Andreas Enge Subject: Re: Some things to be aware of for docs Date: Sat, 27 Feb 2016 19:13:48 +0100 Message-ID: <20160227181348.GA3196@solar> References: <56C2281B.90104@gmail.com> <8737sher6b.fsf@gnu.org> <20160224212808.GA5991@solar> <87bn72xdvf.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-15 Content-Transfer-Encoding: 8bit Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:50156) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aZjNO-00025O-FK for help-guix@gnu.org; Sat, 27 Feb 2016 13:13:59 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aZjNK-0004MU-GK for help-guix@gnu.org; Sat, 27 Feb 2016 13:13:58 -0500 Received: from mailrelay1.public.one.com ([91.198.169.124]:24006) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aZjNK-0004M7-4y for help-guix@gnu.org; Sat, 27 Feb 2016 13:13:54 -0500 Content-Disposition: inline In-Reply-To: <87bn72xdvf.fsf@gnu.org> List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org Sender: help-guix-bounces+gcggh-help-guix=m.gmane.org@gnu.org To: Ludovic =?iso-8859-15?Q?Court=E8s?= Cc: Esteban Enrique , help-guix@gnu.org On Sat, Feb 27, 2016 at 06:27:32PM +0100, Ludovic Courtès wrote: > Andreas Enge skribis: > > One of the doc patches I just pushed has added this reminder. > Really? I was referring to this bit from 2014: Indeed I am mistaken; I also only find the snippet you quote. Sorry for the noise! Andreas