Re: [RFD] XFS documentation project

[Jeff Liu <jeff.liu@oracle.com>]

What an excellent idea!! Thanks for for bringing this up.

I might not able to contribute much things to this project by writing
document directly given that my English skill is poor :(, but I can
translate them to Chinese version.

Moreover, I definitely would like to get involved in the the doc review
and forward this email to our internal Linux/XFS technical documentation
experts to see their opinions.

Thanks,
-Jeff

On 12/13 2013 15:05 PM, Dave Chinner wrote:
> Hi folks,
> 
> Documentation. Yeah, that bug-bear. Never up to date, never contains
> the right stuff, spread all over the place, in nasty formats that
> are hard to maintain, blah, blah, blah.
> 
> We've got some stuff in publican format in a repo on kernel.org
> (http://git.kernel.org/cgit/fs/xfs/xfsdocs-xml-dev.git/), there's
> stuff on the wiki at xfs.org (e.g. the XFS FAQ), on oss.sgi.com.
> there's man pages in  xfsprogs, Documentation/filesystems/xfs* in
> the kernel tree, and there's random user and admin guides written by
> SGI, RH, SuSE, and so on.
> 
> They are all in different formats, under different licenses, and
> contain a heap of information that is either duplicated,
> conflicting, out of date, no longer relevant or just plain wrong.
> 
> We don't have somewhere we we can record all the information that
> comes out of mailing list discussions - we're not capturing useful
> information about optimal setups for given workloads, when you
> should some feature, etc, and that's a loss for everyone.
> 
> What knowledge we do have is mostly tied up in documents that are
> hard to modify, share or use as the basis for other documentation.
> And there is a huge amount of knowledge that is tied up in our
> heads that isn't documented anywhere.
> 
> That's what I'd like to capture via an "upstream" XFS documentation
> project. What I envisiage is that we end up with with a repository
> that users, developers and tech writers contribute changes to, then
> distros pull the result back down, trim and "skin" it for their
> distro documentation.
> 
> I'd like to see if we can get a project underway to acheive
> this goal. The documentation I'm thinking of includes administration
> guides, filesystem capabilities, strengths, weaknesses, best
> practices, optimisation techniques, triage and fault analysis,
> on-disk format specification, developer guides, education material,
> etc.
> 
> I'm not thinking small here - we already have these things in
> various levels of detail spread all over the place. However, I'm not
> a documentation expert, so I'm kind of fishing around for ideas and
> ways to work towards this goal.  I know what problems I'd like to
> solve and what outcomes I'd like see, but how to get there is
> something we need help to plan and implement.
> 
> IOWs, this is an undertaking that I can not do alone, so consider
> this a call for help. Anyone willing to put their hat in the ring,
> or know someone who might be able to help?
> 
> Cheers,
> 
> Dave.
> 

_______________________________________________
xfs mailing list
xfs@oss.sgi.com
http://oss.sgi.com/mailman/listinfo/xfs