all messages for Guix-related lists mirrored at yhetil.org
 help / color / mirror / Atom feed
* bug#47630: Improve guix manual installation docs
@ 2021-04-07  4:55 bo0od
  2021-06-08 17:48 ` Eric Brown
  2021-07-02 16:47 ` zimoun
  0 siblings, 2 replies; 9+ messages in thread
From: bo0od @ 2021-04-07  4:55 UTC (permalink / raw)
  To: 47630

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!




^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#47630: Improve guix manual installation docs
  2021-04-07  4:55 bug#47630: Improve guix manual installation docs bo0od
@ 2021-06-08 17:48 ` Eric Brown
  2021-07-02 16:47 ` zimoun
  1 sibling, 0 replies; 9+ messages in thread
From: Eric Brown @ 2021-06-08 17:48 UTC (permalink / raw)
  To: bo0od; +Cc: 47630

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.





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#47630: Improve guix manual installation docs
  2021-04-07  4:55 bug#47630: Improve guix manual installation docs bo0od
  2021-06-08 17:48 ` Eric Brown
@ 2021-07-02 16:47 ` zimoun
  2021-07-15 12:56   ` bo0od
  1 sibling, 1 reply; 9+ messages in thread
From: zimoun @ 2021-07-02 16:47 UTC (permalink / raw)
  To: bo0od; +Cc: 47630

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




^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#47630: Improve guix manual installation docs
  2021-07-02 16:47 ` zimoun
@ 2021-07-15 12:56   ` bo0od
  2021-08-17 21:28     ` zimoun
  0 siblings, 1 reply; 9+ messages in thread
From: bo0od @ 2021-07-15 12:56 UTC (permalink / raw)
  To: zimoun; +Cc: 47630

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




^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#47630: Improve guix manual installation docs
  2021-07-15 12:56   ` bo0od
@ 2021-08-17 21:28     ` zimoun
  2021-09-14 10:35       ` zimoun
  0 siblings, 1 reply; 9+ messages in thread
From: zimoun @ 2021-08-17 21:28 UTC (permalink / raw)
  To: bo0od; +Cc: 47630

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




^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#47630: Improve guix manual installation docs
  2021-08-17 21:28     ` zimoun
@ 2021-09-14 10:35       ` zimoun
  2021-09-14 14:50         ` bo0od
  0 siblings, 1 reply; 9+ messages in thread
From: zimoun @ 2021-09-14 10:35 UTC (permalink / raw)
  To: bo0od; +Cc: 47630

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




^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#47630: Improve guix manual installation docs
  2021-09-14 10:35       ` zimoun
@ 2021-09-14 14:50         ` bo0od
  2021-09-14 15:41           ` zimoun
  0 siblings, 1 reply; 9+ messages in thread
From: bo0od @ 2021-09-14 14:50 UTC (permalink / raw)
  To: zimoun; +Cc: 47630

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
> 




^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#47630: Improve guix manual installation docs
  2021-09-14 14:50         ` bo0od
@ 2021-09-14 15:41           ` zimoun
  2021-09-26  8:17             ` bo0od
  0 siblings, 1 reply; 9+ messages in thread
From: zimoun @ 2021-09-14 15:41 UTC (permalink / raw)
  To: bo0od; +Cc: 47630

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




^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#47630: Improve guix manual installation docs
  2021-09-14 15:41           ` zimoun
@ 2021-09-26  8:17             ` bo0od
  0 siblings, 0 replies; 9+ messages in thread
From: bo0od @ 2021-09-26  8:17 UTC (permalink / raw)
  To: zimoun; +Cc: 47630

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




^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2021-09-26  8:19 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-04-07  4:55 bug#47630: Improve guix manual installation docs bo0od
2021-06-08 17:48 ` Eric Brown
2021-07-02 16:47 ` zimoun
2021-07-15 12:56   ` bo0od
2021-08-17 21:28     ` zimoun
2021-09-14 10:35       ` zimoun
2021-09-14 14:50         ` bo0od
2021-09-14 15:41           ` zimoun
2021-09-26  8:17             ` bo0od

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.