Re: Some things to be aware of for docs

[Nils Gillmann]

Esteban Enrique <address@hidden> 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