[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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

 * * *

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*

(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
 * 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
 * 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: