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@xxxxxxxxxxx http://oss.sgi.com/mailman/listinfo/xfs
