proofreading the installation-guide
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
Reply to: