XFS documentation project
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.
Signature · 7 lines
Dave Chinner [email protected] _______________________________________________ xfs mailing list [email protected] http://oss.sgi.com/mailman/listinfo/xfs
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
Quoted 47 lines · 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.
Quoted 8 lines
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
[email protected]
http://oss.sgi.com/mailman/listinfo/xfs