GNU bug report logs - #47630
Improve guix manual installation docs

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 47630 in the body.
You can then email your comments to 47630 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: bo0od <bo0od <at> riseup.net>
To: bug-guix <at> gnu.org
Subject: Improve guix manual installation docs
Date: Wed, 7 Apr 2021 04:55:25 +0000

Hi There,

Checking here:

https://guix.gnu.org/manual/en/html_node/Manual-Installation.html

This section actually misses alot of commands and its not nice to give 
only hint commands and leave step by step explanation e.g:

https://guix.gnu.org/manual/en/html_node/Keyboard-Layout-and-Networking-and-Partitioning.html

"parted /dev/sda set 1 esp on"

This command wont work without labeling the partition "parted /dev/sda 
-- mklabel gpt" and so on..

This mean user cant copy and paste he need to figure out the errors 
while hes follow the documentation because it doesn't give to the user 
the full picture.

I suggest to take a look at NixOS docs which goes step by step without 
jumping any necessary one:

https://nixos.org/manual/nixos/stable/index.html#sec-installation-partitioning

(Unclear documentation causes unsolvable or ambiguous questions from 
users and its troublesome to the support team to re-add the missing 
parts of the docs in their support.(Assuming they figured out where is 
the issue user is falling in.))

ThX!

Message #8 received at 47630 <at> debbugs.gnu.org (full text, mbox):

From: Eric Brown <ecbrown <at> ericcbrown.com>
To: bo0od <bo0od <at> riseup.net>
Cc: 47630 <at> debbugs.gnu.org
Subject: Re: bug#47630: Improve guix manual installation docs
Date: Tue, 08 Jun 2021 12:48:42 -0500

bo0od <bo0od <at> riseup.net> writes:

> Hi There,
>
> Checking here:
>
> https://guix.gnu.org/manual/en/html_node/Manual-Installation.html
>
> This section actually misses alot of commands and its not nice to give
> only hint commands and leave step by step explanation e.g:
>
> https://guix.gnu.org/manual/en/html_node/Keyboard-Layout-and-Networking-and-Partitioning.html
>
> "parted /dev/sda set 1 esp on"
>
> This command wont work without labeling the partition "parted /dev/sda
> -- mklabel gpt" and so on..
>
> This mean user cant copy and paste he need to figure out the errors
> while hes follow the documentation because it doesn't give to the user 
> the full picture.
>
> I suggest to take a look at NixOS docs which goes step by step without
> jumping any necessary one:
>
> https://nixos.org/manual/nixos/stable/index.html#sec-installation-partitioning
>
> (Unclear documentation causes unsolvable or ambiguous questions from
> users and its troublesome to the support team to re-add the missing 
> parts of the docs in their support.(Assuming they figured out where is
> the issue user is falling in.))
>
> ThX!

If you would have rolled your suggestions into a patch, then your
support team would not have to keep re-implementing it.

Message #11 received at 47630 <at> debbugs.gnu.org (full text, mbox):

From: zimoun <zimon.toutoune <at> gmail.com>
To: bo0od <bo0od <at> riseup.net>
Cc: 47630 <at> debbugs.gnu.org
Subject: Re: bug#47630: Improve guix manual installation docs
Date: Fri, 02 Jul 2021 18:47:44 +0200

Hi,

On Wed, 07 Apr 2021 at 04:55, bo0od <bo0od <at> riseup.net> wrote:

> Checking here:
>
> https://guix.gnu.org/manual/en/html_node/Manual-Installation.html
>
> This section actually misses alot of commands and its not nice to give only
> hint commands and leave step by step explanation e.g:
>
> https://guix.gnu.org/manual/en/html_node/Keyboard-Layout-and-Networking-and-Partitioning.html
>
> "parted /dev/sda set 1 esp on"
>
> This command wont work without labeling the partition "parted /dev/sda --
> mklabel gpt" and so on..
>
> This mean user cant copy and paste he need to figure out the errors while hes
> follow the documentation because it doesn't give to the user the full picture.
>
> I suggest to take a look at NixOS docs which goes step by step without jumping
> any necessary one:
>
> https://nixos.org/manual/nixos/stable/index.html#sec-installation-partitioning
>
> (Unclear documentation causes unsolvable or ambiguous questions from users and
> its troublesome to the support team to re-add the missing parts of the docs in
> their support.(Assuming they figured out where is the issue user is falling
> in.))

Thanks for your report.  Could you propose a concrete wording solving
the issues you see?

Thanks,
simon

Message #14 received at 47630 <at> debbugs.gnu.org (full text, mbox):

From: bo0od <bo0od <at> riseup.net>
To: zimoun <zimon.toutoune <at> gmail.com>
Cc: 47630 <at> debbugs.gnu.org
Subject: Re: bug#47630: Improve guix manual installation docs
Date: Thu, 15 Jul 2021 12:56:17 +0000

> Could you propose a concrete wording solving
> the issues you see

Not really because english is not my mother tongue so there going to be 
errors in grammars, choosing of words..etc so better to be written by 
someone who has better english than me.

But for the commands to go on step by step i can give that with little 
text and any webadmin can pick it up and arrange it accordingly.

If guix documentation built on wikimedia it would be much easier because 
i can register and upload my changes and can be reviewed and updated, 
But using email for this is not the best way to achieve it but what to do..



zimoun:
> Hi,
> 
> On Wed, 07 Apr 2021 at 04:55, bo0od <bo0od <at> riseup.net> wrote:
> 
>> Checking here:
>>
>> https://guix.gnu.org/manual/en/html_node/Manual-Installation.html
>>
>> This section actually misses alot of commands and its not nice to give only
>> hint commands and leave step by step explanation e.g:
>>
>> https://guix.gnu.org/manual/en/html_node/Keyboard-Layout-and-Networking-and-Partitioning.html
>>
>> "parted /dev/sda set 1 esp on"
>>
>> This command wont work without labeling the partition "parted /dev/sda --
>> mklabel gpt" and so on..
>>
>> This mean user cant copy and paste he need to figure out the errors while hes
>> follow the documentation because it doesn't give to the user the full picture.
>>
>> I suggest to take a look at NixOS docs which goes step by step without jumping
>> any necessary one:
>>
>> https://nixos.org/manual/nixos/stable/index.html#sec-installation-partitioning
>>
>> (Unclear documentation causes unsolvable or ambiguous questions from users and
>> its troublesome to the support team to re-add the missing parts of the docs in
>> their support.(Assuming they figured out where is the issue user is falling
>> in.))
> 
> Thanks for your report.  Could you propose a concrete wording solving
> the issues you see?
> 
> Thanks,
> simon
> 

Message #17 received at 47630 <at> debbugs.gnu.org (full text, mbox):

From: zimoun <zimon.toutoune <at> gmail.com>
To: bo0od <bo0od <at> riseup.net>
Cc: 47630 <at> debbugs.gnu.org
Subject: Re: bug#47630: Improve guix manual installation docs
Date: Tue, 17 Aug 2021 23:28:12 +0200

Hi,

On Thu, 15 Jul 2021 at 12:56, bo0od <bo0od <at> riseup.net> wrote:
>> Could you propose a concrete wording solving
>> the issues you see
>
> Not really because english is not my mother tongue so there going to be errors
> in grammars, choosing of words..etc so better to be written by someone who has
> better english than me.
>
> But for the commands to go on step by step i can give that with little text
> and any webadmin can pick it up and arrange it accordingly.
>
> If guix documentation built on wikimedia it would be much easier because i can
> register and upload my changes and can be reviewed and updated, But using
> email for this is not the best way to achieve it but what to do..

Maybe you could provide what you find missing and where in the manual,
with little text.  It should be a good start for pointing what and how
to improve.


All the best,
simon

Message #20 received at 47630 <at> debbugs.gnu.org (full text, mbox):

From: zimoun <zimon.toutoune <at> gmail.com>
To: bo0od <bo0od <at> riseup.net>
Cc: 47630 <at> debbugs.gnu.org
Subject: Re: bug#47630: Improve guix manual installation docs
Date: Tue, 14 Sep 2021 12:35:04 +0200

Hi,

On Tue, 17 Aug 2021 at 23:28, zimoun <zimon.toutoune <at> gmail.com> wrote:
> On Thu, 15 Jul 2021 at 12:56, bo0od <bo0od <at> riseup.net> wrote:
>>> Could you propose a concrete wording solving
>>> the issues you see
>>
>> Not really because english is not my mother tongue so there going to be errors
>> in grammars, choosing of words..etc so better to be written by someone who has
>> better english than me.
>>
>> But for the commands to go on step by step i can give that with little text
>> and any webadmin can pick it up and arrange it accordingly.
>>
>> If guix documentation built on wikimedia it would be much easier because i can
>> register and upload my changes and can be reviewed and updated, But using
>> email for this is not the best way to achieve it but what to do..
>
> Maybe you could provide what you find missing and where in the manual,
> with little text.  It should be a good start for pointing what and how
> to improve.

I plan to close this report if there is no concrete patch attached.
Because personally I do not see what could be done.

All the best,
simon

Message #23 received at 47630 <at> debbugs.gnu.org (full text, mbox):

From: bo0od <bo0od <at> riseup.net>
To: zimoun <zimon.toutoune <at> gmail.com>
Cc: 47630 <at> debbugs.gnu.org
Subject: Re: bug#47630: Improve guix manual installation docs
Date: Tue, 14 Sep 2021 14:50:21 +0000

Fix the documentation as steps works for the end user as if he follow it 
1 by 1 copy/paste (similar to nix docs as example), Otherwise current 
steps in the docs just junk to the end user. (you dont expect users to 
know and finish steps themselves)

zimoun:
> Hi,
> 
> On Tue, 17 Aug 2021 at 23:28, zimoun <zimon.toutoune <at> gmail.com> wrote:
>> On Thu, 15 Jul 2021 at 12:56, bo0od <bo0od <at> riseup.net> wrote:
>>>> Could you propose a concrete wording solving
>>>> the issues you see
>>>
>>> Not really because english is not my mother tongue so there going to be errors
>>> in grammars, choosing of words..etc so better to be written by someone who has
>>> better english than me.
>>>
>>> But for the commands to go on step by step i can give that with little text
>>> and any webadmin can pick it up and arrange it accordingly.
>>>
>>> If guix documentation built on wikimedia it would be much easier because i can
>>> register and upload my changes and can be reviewed and updated, But using
>>> email for this is not the best way to achieve it but what to do..
>>
>> Maybe you could provide what you find missing and where in the manual,
>> with little text.  It should be a good start for pointing what and how
>> to improve.
> 
> I plan to close this report if there is no concrete patch attached.
> Because personally I do not see what could be done.
> 
> All the best,
> simon
> 

Message #26 received at 47630 <at> debbugs.gnu.org (full text, mbox):

From: zimoun <zimon.toutoune <at> gmail.com>
To: bo0od <bo0od <at> riseup.net>
Cc: 47630 <at> debbugs.gnu.org
Subject: Re: bug#47630: Improve guix manual installation docs
Date: Tue, 14 Sep 2021 17:41:36 +0200

Hi,

On Tue, 14 Sept 2021 at 16:51, bo0od <bo0od <at> riseup.net> wrote:

> Fix the documentation as steps works for the end user as if he follow it
> 1 by 1 copy/paste (similar to nix docs as example), Otherwise current
> steps in the docs just junk to the end user. (you dont expect users to
> know and finish steps themselves)

I proposed you to write down these steps as a starting point for
improving the manual to turn it into a patch (for the Manual or the
Cookbook); this is actionable.  Otherwise say « improve this part of
the manual » is not constructive; this is not actionable.  I (and
probably others) do not see what could be improved in this area so it
appears to me hard to improve something that I do not know what. :-)

Last, the manual says:

        This option requires familiarity with GNU/Linux, with the shell,
        and with common administration tools. If you think this is not
        for you, consider using the guided graphical installer.

<https://guix.gnu.org/manual/en/html_node/Manual-Installation.html>

Therefore, it appears to me expected that this section provides only
command hints and not one by one step to complete all the process.
Other said, I expect that user who does not know how to fully complete
will run the Graphical Installer.  Does Nix have a Graphical
Installer?


All the best,
simon

Message #31 received at 47630 <at> debbugs.gnu.org (full text, mbox):

From: bo0od <bo0od <at> riseup.net>
To: zimoun <zimon.toutoune <at> gmail.com>
Cc: 47630 <at> debbugs.gnu.org
Subject: Re: bug#47630: Improve guix manual installation docs
Date: Sun, 26 Sep 2021 08:17:35 +0000

> I proposed you to write down these steps as a starting point for
> improving the manual to turn it into a patch

Will do that for next guix release hopefully.

zimoun:
> Hi,
> 
> On Tue, 14 Sept 2021 at 16:51, bo0od <bo0od <at> riseup.net> wrote:
> 
>> Fix the documentation as steps works for the end user as if he follow it
>> 1 by 1 copy/paste (similar to nix docs as example), Otherwise current
>> steps in the docs just junk to the end user. (you dont expect users to
>> know and finish steps themselves)
> 
> I proposed you to write down these steps as a starting point for
> improving the manual to turn it into a patch (for the Manual or the
> Cookbook); this is actionable.  Otherwise say « improve this part of
> the manual » is not constructive; this is not actionable.  I (and
> probably others) do not see what could be improved in this area so it
> appears to me hard to improve something that I do not know what. :-)
> 
> Last, the manual says:
> 
>          This option requires familiarity with GNU/Linux, with the shell,
>          and with common administration tools. If you think this is not
>          for you, consider using the guided graphical installer.
> 
> <https://guix.gnu.org/manual/en/html_node/Manual-Installation.html>
> 
> Therefore, it appears to me expected that this section provides only
> command hints and not one by one step to complete all the process.
> Other said, I expect that user who does not know how to fully complete
> will run the Graphical Installer.  Does Nix have a Graphical
> Installer?
> 
> 
> All the best,
> simon
> 

Message #34 received at 47630 <at> debbugs.gnu.org (full text, mbox):

From: zimoun <zimon.toutoune <at> gmail.com>
To: bo0od <bo0od <at> riseup.net>
Cc: 47630 <at> debbugs.gnu.org
Subject: Re: bug#47630: Improve guix manual installation docs
Date: Tue, 04 Jan 2022 23:53:41 +0100

Hi,

On Sun, 26 Sep 2021 at 08:17, bo0od <bo0od <at> riseup.net> wrote:
>> I proposed you to write down these steps as a starting point for
>> improving the manual to turn it into a patch
>
> Will do that for next guix release hopefully.

The next release is coming.  See [1].  Therefore, do you plan to fix
#47630?  Otherwise, let close it since the backlog is already enough
long. :-)

1: <https://lists.gnu.org/archive/html/guix-devel/2022-01/msg00055.html>
2: <http://issues.guix.gnu.org/issue/47630>


Cheers,
simon

Message #37 received at 47630 <at> debbugs.gnu.org (full text, mbox):

From: zimoun <zimon.toutoune <at> gmail.com>
To: bo0od <bo0od <at> riseup.net>
Cc: 47630 <at> debbugs.gnu.org
Subject: Re: bug#47630: Improve guix manual installation docs
Date: Thu, 23 Jun 2022 11:52:17 +0200

Hi,

On Tue, 04 Jan 2022 at 23:53, zimoun <zimon.toutoune <at> gmail.com> wrote:
> On Sun, 26 Sep 2021 at 08:17, bo0od <bo0od <at> riseup.net> wrote:

>>> I proposed you to write down these steps as a starting point for
>>> improving the manual to turn it into a patch
>>
>> Will do that for next guix release hopefully.
>
>                                        Therefore, do you plan to fix
> #47630?  Otherwise, let close it since the backlog is already enough
> long. :-)

I am proposing to close this wishlist [1].  Any objection?

1: <http://issues.guix.gnu.org/issue/47630>


Cheers,
simon

Message #40 received at 47630 <at> debbugs.gnu.org (full text, mbox):

From: bo0od <bo0od <at> riseup.net>
To: zimoun <zimon.toutoune <at> gmail.com>
Cc: 47630 <at> debbugs.gnu.org
Subject: Re: bug#47630: Improve guix manual installation docs
Date: Fri, 24 Jun 2022 10:25:31 +0000

Feel free to do that 1.4 took more than it should and might never see 
the sun anytime soon.

zimoun:
> Hi,
> 
> On Tue, 04 Jan 2022 at 23:53, zimoun <zimon.toutoune <at> gmail.com> wrote:
>> On Sun, 26 Sep 2021 at 08:17, bo0od <bo0od <at> riseup.net> wrote:
> 
>>>> I proposed you to write down these steps as a starting point for
>>>> improving the manual to turn it into a patch
>>>
>>> Will do that for next guix release hopefully.
>>
>>                                         Therefore, do you plan to fix
>> #47630?  Otherwise, let close it since the backlog is already enough
>> long. :-)
> 
> I am proposing to close this wishlist [1].  Any objection?
> 
> 1: <http://issues.guix.gnu.org/issue/47630>
> 
> 
> Cheers,
> simon

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.