A month ago in #789604, Justin B Rye wrote: > Hmm, well, I've never proofread the installation-guide as a whole. I > ought to get round to doing that some time.
I'm trying to work out where I'd start with this. I can see things that need fixing, but they fall into several different categories and I don't know if it makes sense to try to deal with all of them at once. * * * First, the deep-rooted termininological issues that I'd prefer to have sane answers for before I start fiddling with details: * why is there so little mention of BD media? It seems to me that we should almost never say "CDs and DVDs"; we should settle on a cover-term like "optical media" and always use that. The one time it does mention "BD-ROMS" it claims that it's going to use "CD-ROMs" as a cover-term... but then it doesn't. * D-I seems to have standardised on the term "MD devices", expanding "MD" as "Multidisk Device" (what, so they're "Multidisk Device devices"?); but officially "md" stands for "Multiple Device". Besides, if what we're talking about is in fact a software RAID array, why don't we just call it that? * is there any hope of getting rid of the crazy backwards jargon of "low priority installs"? When you ask for "Expert mode", you aren't lowering the priority of the install (i.e. declaring it less urgent); you aren't even lowering the priority of the questions it asks. What you're doing is lowering the amount of filtering-by-priority applied to debconf prompts - or to put that another way, you're asking for a low *simplification* install. (Perhaps I should make these three separate bugreports?) * * * Second, questions specific to the installation-guide's docbook, which again it would be nice to have answers for before I start trying to produce patches. (In fact, maybe the answers are or should be in a README somewhere?) * Structure - some of the XML files seem to be unused relics, but it's hard to tell which... * <tag> questions - e.g.: <command> is used fairly consistently for executables (like grub), and <classinfo> for some reason marks Debian packages (like grub-pc), but what do we do with "GRUB"? * Should all <title>s be titlecase? Could we switch to sentencecase? * &entity questions - when am I meant to say "Debian" and when is it "&debian;"? This like many of these entities seems to have no obvious function other than to make the source harder to interpret... * The &d-i; entity expands to "debian-installer" in bold verbatim lowercase. If that is in effect the brandname of the software project then presumably we shouldn't be talking about "the &d-i;" - that ought to be "the Debian installer". * * * Third, the various categories of routine maintenance: * Decobwebbing - all those examples of tiny IDE hard drives with ext3 file systems. * systemd-proofing - stuff about initscripts, /etc/inittab, eth0. * When do we say "APT", when is it "apt-get"/"aptitude"/"apt"? * Non-native-English-speakerisms - the usual objectless allows and Teutonic respectivelies, plus one that's especially common in D-I: yes, CDs are "(installation) media", but one CD isn't "a medium". * All those references to dhcp and ram and ips. * All those "OldWorld PowerMacs" (canonically four words). * Standardi[sz]ation issues (mostly "behaviour"). * General phrasing upgrades (mostly to reduce repetition). * Optional-extra "house style" tweaks like adding Harvard commas. -- JBR with qualifications in linguistics, experience as a Debian sysadmin, and probably no clue about this particular package -- To UNSUBSCRIBE, email to debian-boot-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org Archive: https://lists.debian.org/20150726121518.ga14...@xibalba.demon.co.uk