Re: Some things to be aware of for docs

[Leo Famulari <leo@famulari.name>]

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.