bug#47630: Improve guix manual installation docs

bug#47630: Improve guix manual installation docs

[bo0od]

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!

bug#47630: Improve guix manual installation docs

[Eric Brown]

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

bug#47630: Improve guix manual installation docs

[zimoun]

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

bug#47630: Improve guix manual installation docs

[bo0od]

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

bug#47630: Improve guix manual installation docs

[zimoun]

Hi,

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.


All the best,
simon

bug#47630: Improve guix manual installation docs

[zimoun]

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

bug#47630: Improve guix manual installation docs

[bo0od]

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

bug#47630: Improve guix manual installation docs

[zimoun]

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

bug#47630: Improve guix manual installation docs

[bo0od]

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

bug#47630: Improve guix manual installation docs

[zimoun]

Hi,

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.

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

bug#47630: Improve guix manual installation docs

[zimoun]

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

bug#47630: Improve guix manual installation docs

[bo0od]

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