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.