Re: wiki vs man pages

From: Marc MERLIN <marc@merlins.org>
To: Qu Wenruo <quwenruo@cn.fujitsu.com>
Cc: dsterba@suse.cz, linux-btrfs@vger.kernel.org
Subject: Re: wiki vs man pages
Date: Sun, 13 Apr 2014 18:45:20 -0700	[thread overview]
Message-ID: <20140414014520.GA20550@merlins.org> (raw)
In-Reply-To: <534B36FC.3060300@cn.fujitsu.com>

On Mon, Apr 14, 2014 at 09:16:44AM +0800, Qu Wenruo wrote:
> >Generally, would you agree to putting more links to the wiki in man pages
> >since man pages are not forever but sure take a long time to update on the
> >installed based and the wiki can be up to date for everyone right away?
> >(I'm not saying to remove info from the man pages, but more something like
> >"btrfs is changing quickly, more up to date information can be found on the
> >wiki page for
> >raid56: https://btrfs.wiki.kernel.org/index.php/RAID56
> >or
> >btrfsck: https://btrfs.wiki.kernel.org/index.php/Btrfsck
> >btrfs restore: https://btrfs.wiki.kernel.org/index.php/Restore
> >
> >Thanks,
> >Marc
> That's pretty nice and helpful.
> But one of my concern is that wiki changes are not shown as patches in 
> mail list and somewhat
> independent from btrfs-progs,
> so if some developers changed the behavior of RAID56/btrfsck/restore, he 
> or she may only modify the man page
> but not wiki page.
> 
> Any good idea to synchronise wiki pages and man pages?

You raise a good question.

I think the wiki should not be there to list all the options that are in the
man page. As a result, the wiki should not get out of sync with man pages.

The wiki can explain how to use the tools, like some of the pages I listed
above, or this page
http://marc.merlins.org/perso/btrfs/2014-03.html#Btrfs-Tips_-Btrfs-Scrub-and-Btrfs-Filesystem-Repair

A page like this explains what your options are, and what it recommended
including links to other resources.
Man pages are more "these are the options to use this specific program".
In turn the man page cannot be very long and explain all the scenario or
explain how this tools works with other tools, so it can point to the wiki
that has HOWTOs.

So to answer your question, I would say that the man pages should indeed be
updated as the programs/binaries get updated, whereas the wiki pages can get
updated as needed and refer to bugs in the kernel, or missing features, or
features that just got added/improved in kwere kernels.
And also like in the page above, generally give an overview of parts of
btrfs.

Does that make sense?

Marc
-- 
"A mouse is a device used to point at the xterm you want to type in" - A.S.R.
Microsoft is to operating systems ....
                                      .... what McDonalds is to gourmet cooking
Home page: http://marc.merlins.org/  