Some things to be aware of for docs

Some things to be aware of for docs

[Esteban Enrique]

[-- Attachment #1: Type: text/plain, Size: 1349 bytes --]

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?



[-- Attachment #2: Type: text/html, Size: 1671 bytes --]

Re: Some things to be aware of for docs

[Leo Famulari]

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.

Re: Some things to be aware of for docs

[myglc2]

Leo Famulari <leo@famulari.name> 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.

Re: Some things to be aware of for docs

[Esteban Enrique]

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.

Re: Some things to be aware of for docs

[Nils Gillmann]

Leo Famulari <leo@famulari.name> 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

Re: Some things to be aware of for docs

[Nils Gillmann]

Esteban Enrique <esteban.enrique.97@gmail.com> 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

Re: Some things to be aware of for docs

[Leo Famulari]

On Tue, Feb 16, 2016 at 12:54:34AM +0100, Nils Gillmann wrote:
> Leo Famulari <leo@famulari.name> 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.

Re: Some things to be aware of for docs

[Esteban Enrique]

[-- Attachment #1: Type: text/plain, Size: 1136 bytes --]

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 <myglc2@gmail.com> wrote:

> Leo Famulari <leo@famulari.name> 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.
>
>
>

[-- Attachment #2: Type: text/html, Size: 1646 bytes --]

Re: Some things to be aware of for docs

[Ludovic Courtès]

Esteban Enrique <esteban.enrique.97@gmail.com> 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:
<http://git.savannah.gnu.org/cgit/guix.git/tree/doc/guix.texi#n5757>.

But I definitely sympathize with Leo’s comment: I’d 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’s a reminder, but it’s easily overlooked.  ;-)  Anyway, it’s a bug
that should be fixed so the reminder isn’t even necessary.

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

It’s tricky, because we don’t want to “write in the stone” 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’.

Re: Some things to be aware of for docs

[Andreas Enge]

On Wed, Feb 24, 2016 at 10:26:04PM +0100, Ludovic Courtès wrote:
> Esteban Enrique <esteban.enrique.97@gmail.com> 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

Re: Some things to be aware of for docs

[Ludovic Courtès]

Andreas Enge <andreas@enge.fr> skribis:

> On Wed, Feb 24, 2016 at 10:26:04PM +0100, Ludovic Courtès wrote:
>> Esteban Enrique <esteban.enrique.97@gmail.com> 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.

Really?  I was referring to this bit from 2014:

  @quotation Note
  @c The paragraph below refers to the problem discussed at
  @c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
  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’.

Re: Some things to be aware of for docs

[Andreas Enge]

On Sat, Feb 27, 2016 at 06:27:32PM +0100, Ludovic Courtès wrote:
> Andreas Enge <andreas@enge.fr> 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