| Summary: | Multipathing I/O & Gentoo Documentation | ||
|---|---|---|---|
| Product: | [OLD] Docs on www.gentoo.org | Reporter: | Matt Summers (RETIRED) <quantumsummers> |
| Component: | New Documentation | Assignee: | nm (RETIRED) <nightmorph> |
| Status: | RESOLVED FIXED | ||
| Severity: | enhancement | CC: | docs-team, steve.rucker, tsunam |
| Priority: | High | ||
| Version: | unspecified | ||
| Hardware: | All | ||
| OS: | Linux | ||
| Whiteboard: | |||
| Package list: | Runtime testing required: | --- | |
| Attachments: |
Multipathing I/O and Gentoo XML
Version 2 of the Multipath XML Fixed some invalid tags improved guidexml |
||
|
Description
Matt Summers (RETIRED)
2008-07-31 20:51:21 UTC
Created attachment 161880 [details]
Multipathing I/O and Gentoo XML
Comment on attachment 161880 [details]
Multipathing I/O and Gentoo XML
In the future, please attach files with the MIME type of text/plain, otherwise it can't be easily viewed in the browser. Thanks for the doc! Will review.
The draft needs lots of cleanups. ** Coding style notes ** Please refer to the GuideXML coding style document here: http://www.gentoo.org/doc/en/xml-guide.xml Specifically, there should not be tabs or indenting of block level elements such as <p>, <section>, <body>, and the like. Also, when used inside <pre>, the <i> tag is only for user input -- commands that users should run, not for output. Linewrapping needs to be fixed everywhere -- set your editor to wrap at 80 columns; refer to the Xfce guide here for how it should look: http://www.gentoo.org/doc/en/xfce-config.xml?passthru=1 In vim/gvim, you can set the proper wrapping with "set textwidth=80" in your .vimrc or .gvimrc (we like to use vim ;)). ** Content notes ** No need for RPM-based distro instructions. Our documents are written for Gentoo users; anything else but Gentoo-related material is extraneous. Besides, given that we're a source-based distro, with very few exceptions our guides work as-is for many other distros, since we go with the upstream defaults. some of that is from me nightmorph. Blame me for dealing with rpm and gentoo for the documentation I provided. (In reply to comment #4) > some of that is from me nightmorph. Blame me for dealing with rpm and gentoo > for the documentation I provided. > Shocked, yes, I am SHOCKED that you work with RPMs. SHOCKED, I say! :p Anyway, aside from this bit and the guideXML formatting, the doc's in great shape so far. I'd suggest to use "Real Menuconfig Names" (including proper capitalization) and writing "probe all luns" in some markup or at least capitalised -- it took me some time to guess what is meant here at a quick glance over the text (it wasn't clear that it refers to a feature discussed in previous paragraph). Ad RPM stuff (yep, I deal with them, too) -- rephrasing it as "On some systems, you might want to use $insert_the_other_command_here instead" would have that nice benefit that our guide might be used even by folks outside of Gentoo, which is Always Good (tm), and therefore shouldn't be removed. And last but not least :), GDP is usually full of trained monkeys willing to convert any form of a useful doc to a properly formatted GuideXML. There's no need to pester our users with something we (actualy you, nightmorph :p) can easily do in a fraction of time, as you're supposed to be the GuideXML master of the day :). Thanks for a nice article, I've always wondered how multipath works under Linux. Created attachment 162453 [details]
Version 2 of the Multipath XML
Updates have been made to the GuideXML formatting and the RPM comment in the configuration section. Also, some acronyms were corrected.
Created attachment 162751 [details]
Fixed some invalid tags
Latest version, fixed some invalid tags. Thanks to Nandeep Mali (n9986) for the help there. Doc team, please review, I consider this ready for prime time.
I've cleaned it up a bit: - Improved coding style - Switched from <i>s to <c>s inside paragraphs - Removed illegal tags inside <comment>s - Added an <abstract> since it's a required thing I also put it online here for ease of use: http://dev.gentoo.org/~rane/other/multipath.xml Now it passes the "xmllint --valid --noout multipath.xml" test. Created attachment 163337 [details]
improved guidexml
any update about this doc team? Okay, I've been editing this thing for awhile now. Lots of cleanups and fixes. Most importantly, I've rearranged the document to something more resembling standard order. Instead of putting installation and configuration at the end, I moved it to just after the introduction. I mean, it just doesn't make sense to throw every last detail about the thing at users, and *then* walk them through the installation and setup. Doesn't read well. So here's the new outline: 1) Introduction 2) Installation and Configuration a. Installation and Tools b. Configuring Gentoo for multipathing 3) Architectural Overview a. Typical configuration b. Setting up your own configuration You can view this new version at my devspace, http://dev.gentoo.org/~nightmorph/multipath.xml Please review and comment, especially on the fixes and touchups I made to the kernel config and "probe all LUNs" sections. Does the new layout work for you? Okay, it's now in CVS: http://www.gentoo.org/doc/en/multipath.xml (Give it some time to show up; the webnodes need to sync.) Thanks to all the liquidustech guys, tsunam, and rane for assembling the thing. Well done; new documentation is very much appreciated. Fixed in CVS. |