[RFD] XFS documentation project

[RFD] XFS documentation project

[Dave Chinner]

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.
-- 
Dave Chinner
david@fromorbit.com

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

Re: [RFD] XFS documentation project

[Jeff Liu]

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