Improve guix manual installation docs

  • Done
  • quality assurance status badge
Details
3 participants
  • bo0od
  • Eric Brown
  • zimoun
Owner
unassigned
Submitted by
bo0od
Severity
wishlist
B
B
bo0od wrote on 7 Apr 2021 06:55
(address . bug-guix@gnu.org)
2b1e7af8-40bc-1603-3cdf-e40dcaff9f98@riseup.net
Hi There,

Checking here:


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


"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:


(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!
E
E
Eric Brown wrote on 8 Jun 2021 19:48
(name . bo0od)(address . bo0od@riseup.net)(address . 47630@debbugs.gnu.org)
87wnr4s0w5.fsf@ericcbrown.com
bo0od <bo0od@riseup.net> writes:

Toggle quote (32 lines)
> 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.
Z
Z
zimoun wrote on 2 Jul 2021 18:47
(name . bo0od)(address . bo0od@riseup.net)(address . 47630@debbugs.gnu.org)
87y2aoll1r.fsf@gmail.com
Hi,

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

Toggle quote (27 lines)
> 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
B
B
bo0od wrote on 15 Jul 2021 14:56
(name . zimoun)(address . zimon.toutoune@gmail.com)(address . 47630@debbugs.gnu.org)
defe8615-0ea0-2b09-a1b3-d11593d4f315@riseup.net
Toggle quote (1 lines)
> 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:
Toggle quote (37 lines)
> Hi,
>
> On Wed, 07 Apr 2021 at 04:55, bo0od <bo0od@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
>
Z
Z
zimoun wrote on 17 Aug 2021 23:28
(name . bo0od)(address . bo0od@riseup.net)(address . 47630@debbugs.gnu.org)
865yw3n4lv.fsf@gmail.com
Hi,

On Thu, 15 Jul 2021 at 12:56, bo0od <bo0od@riseup.net> wrote:
Toggle quote (14 lines)
>> 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
Z
Z
zimoun wrote on 14 Sep 2021 12:35
(name . bo0od)(address . bo0od@riseup.net)(address . 47630@debbugs.gnu.org)
865yv3v413.fsf@gmail.com
Hi,

On Tue, 17 Aug 2021 at 23:28, zimoun <zimon.toutoune@gmail.com> wrote:
Toggle quote (19 lines)
> On Thu, 15 Jul 2021 at 12:56, bo0od <bo0od@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
B
B
bo0od wrote on 14 Sep 2021 16:50
(name . zimoun)(address . zimon.toutoune@gmail.com)(address . 47630@debbugs.gnu.org)
a45e9a7e-6079-8692-0cc3-6f4cc8f2e521@riseup.net
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:
Toggle quote (28 lines)
> Hi,
>
> On Tue, 17 Aug 2021 at 23:28, zimoun <zimon.toutoune@gmail.com> wrote:
>> On Thu, 15 Jul 2021 at 12:56, bo0od <bo0od@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
>
Z
Z
zimoun wrote on 14 Sep 2021 17:41
(name . bo0od)(address . bo0od@riseup.net)(address . 47630@debbugs.gnu.org)
CAJ3okZ1qfYeGu+XkkfcSyuOL6M0zy7DT9ZvoPD3cPOn3mOXDrQ@mail.gmail.com
Hi,

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

Toggle quote (5 lines)
> 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.


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
Z
Z
zimoun wrote on 20 Sep 2021 13:34
control message for bug #47630
(address . control@debbugs.gnu.org)
87zgs7fpkl.fsf@gmail.com
severity 47630 wishlist
quit
B
B
bo0od wrote on 26 Sep 2021 10:17
Re: bug#47630: Improve guix manual installation docs
(name . zimoun)(address . zimon.toutoune@gmail.com)(address . 47630@debbugs.gnu.org)
670eb1b1-8fa5-76ea-8bad-06707622d3a5@riseup.net
Toggle quote (1 lines)
> 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:
Toggle quote (34 lines)
> Hi,
>
> On Tue, 14 Sept 2021 at 16:51, bo0od <bo0od@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
>
Z
Z
zimoun wrote on 4 Jan 2022 23:53
(name . bo0od)(address . bo0od@riseup.net)(address . 47630@debbugs.gnu.org)
8635m3cdu2.fsf@gmail.com
Hi,

On Sun, 26 Sep 2021 at 08:17, bo0od <bo0od@riseup.net> wrote:
Toggle quote (5 lines)
>> 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. :-)



Cheers,
simon
Z
Z
zimoun wrote on 23 Jun 2022 11:52
(name . bo0od)(address . bo0od@riseup.net)(address . 47630@debbugs.gnu.org)
86zgi37lm6.fsf@gmail.com
Hi,

On Tue, 04 Jan 2022 at 23:53, zimoun <zimon.toutoune@gmail.com> wrote:
Toggle quote (11 lines)
> On Sun, 26 Sep 2021 at 08:17, bo0od <bo0od@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?



Cheers,
simon
B
B
bo0od wrote on 24 Jun 2022 12:25
(name . zimoun)(address . zimon.toutoune@gmail.com)(address . 47630@debbugs.gnu.org)
0afc7c46-9ce3-1284-8f87-fa67f816727d@riseup.net
Feel free to do that 1.4 took more than it should and might never see
the sun anytime soon.

zimoun:
Toggle quote (21 lines)
> Hi,
>
> On Tue, 04 Jan 2022 at 23:53, zimoun <zimon.toutoune@gmail.com> wrote:
>> On Sun, 26 Sep 2021 at 08:17, bo0od <bo0od@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
Z
Z
zimoun wrote on 8 Oct 2022 17:13
control message for bug #47630
(address . control@debbugs.gnu.org)
86a666s603.fsf@gmail.com
close 47630
quit
?
Your comment

This issue is archived.

To comment on this conversation send an email to 47630@debbugs.gnu.org

To respond to this issue using the mumi CLI, first switch to it
mumi current 47630
Then, you may apply the latest patchset in this issue (with sign off)
mumi am -- -s
Or, compose a reply to this issue
mumi compose
Or, send patches to this issue
mumi send-email *.patch