[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Some things to be aware of for docs

From: Esteban Enrique
Subject: Re: Some things to be aware of for docs
Date: Mon, 15 Feb 2016 17:51:27 -0500
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Icedove/38.5.0

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

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]