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