Re: Some things to be aware of for docs

[Nils Gillmann]

Leo Famulari <address@hidden> 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