Following up #794936, here's my second bugreport for a big clear
individual issue before I start on a general proofreading sweep.

Section 6.3.3.4 (aka the file "using-d-i/modules/mdcfg.xml") describes
how to set up RAID arrays in D-I.  But instead of just calling them
that it insists on using jargon which users are unlikely to be
familiar with and which isn't even technically correct.

I'm including general proofreading fixes in this patch as well as the
headline problem, because it's all in one .xml file - if I tried to
separate things out into one patch fixing the grammar issues and one
standardising the punctuation and so on then they'd all just trample
on one another's toes.

Here's an annotated copy of the patch (and yes, this time I've
double-checked the attached version is the same file!):

Because absolutely nobody calls them Multidisk Devices, and MD has
never stood for that anyway.  (There are rumours it was once "Mirror
Disk", but it has officially always been "Multiple Device".)

I was going to add that if you Google "Multidisk Devices", it just
goes "did you mean...?" - but in fact if I insist, it will do that
search, and finds Frans Pop filing bug #387696 about this in 2006.
That was allegedly fixed, but here it still is.

If the mdcfg module supported RAID plus some other things then it
might be more pedantically accurate to talk here in terms of using
Multiple Device storage in general.  But it doesn't.  It's talking
about RAID, which was already widely known as RAID before Linux
existed.  So call it RAID!

I'm letting "mountpoints" and "filesystems" get away with being
written as one word, but "harddrive" is a step too far.

(Meanwhile, the day may be approaching when we'll need to say "hard
disk, flash drive, or similar main non-volatile storage system".  Or
maybe we'll be able to use plain "drive" as a cover-term...)

Leaving out this detail wouldn't have been dishonest.

Our default name for RAID arrays should be "RAID arrays".  Referring
to RAID in terms of the Linux kernel driver used for it makes even
less sense when you consider that this installer is also intended foe
use on systems where &arch-kernel; != Linux.

Missing indefinite article.

Users of D-I are never told that they're using mdcfg, so it's fairly
pointless to act as if they'd recognise the name; instead, _introduce_
it here.  Tagging "mdcfg" as a <command> just spoils any plan we might
have for making the <command> tag pull its weight (they might for
instance link to manpages.debian.org - but D-I modules don't have man
pages).  I'm falling back on marking "mdcfg" as a basic <literal> here
(which should result in the same markup as for a <command>), but it's
not clear it's entitled even to this much, since it isn't a word that
users ever need to be treat as a verbatim string...

"Reliability of your data" is subtly wrong.  If my data is the
collected prophetic ramblings of Nostradamus, RAID isn't going to make
it any more reliable!  Just say "improved [...] reliability".

Then the end of the second sentence is the main point of this bug
report.  The result of using mdcfg is _not_ called "Multidisk Device".
It isn't even called "MD".  It's called RAID.  Introduce it as RAID,
then note in case anybody cares that it's implemented in Linux under
the name "md".  (This might even go in a footnote, but we've just had
one of those.)

Don't call it MD, call it RAID, and don't talk as if users had some
way of knowing when they're "in partman".  (Since partman is the thing
the install immediately continues with when you exit mdcfg, it hardly
needs to be named anyway.)

Plus some general tweaks to the English - use "you" consistently
rather than a passive construction, and avoid overdosing on latinisms
(e.g. i.e., etc.).

Don't call it MD, call it RAID.  I've also reorganised the use of
tenses, not because the original version was ungrammatical,
particularly, but just because "this brings depends" is slightly
jarring.

Either of these is idiomatic spoken English, but there are some
styleguides that object to the adverb version.

Just for once I've taken the word "RAID" out here, because although
the acronym expands to "Redundant Array of In(...mumble...) Disks", it
doesn't usually mean an array; "RAID" as a noun generally refers to
the technology in general.

The repetition of "servers" and use of commas in the last sentence
strike me as awkward.  I would also naturally use "between", not
"among", but I'm leaving that since it's often an en-GB/en-US thing.

"Harvard comma", since it's used elsewhere in this page.

Wrong aspectual construction.

I could have added a definite article instead, but the easier
solution is to eliminate the need for one.

"Achieving less redundancy" is ambiguous, especially with something
which can be either good or bad, like redundancy.  The use of "On
the other hand" to separate two things that are both disadvantages
makes it even more confusing, so I've tweaked it for added clarity.

"Copies of the same data as what?"

Just following the usual styleguide rule that low numbers are
written out as words (though using figures in a table is fine, and
you might argue that this is in effect quoting from the table...)

"RAID10 has different layouts" is hard to follow.  Then the rest of
this paragraph suffers slightly from excessively short sentences -
not a common problem in technical writing!  Yes, short tends to be
good, but if you take it too far it ends up choppy and repetitive,
so I've merged the sentence about "near" being the default into the
following one.

The definition of "offset copies" was confusing, so I've called in a
synonym.  It still isn't easy to follow, but at least it doesn't
seem to be saying that in the other layouts copies copy copies.

Consistent capitalisation.

Just making the layout consistent with the other columns.

Ditto.  (The fact that it says "two" rather than "2" was the deciding
vote against referring to a default value as "2" above.)

Well, we're treating it as definitive, so let's give it the
definite article.

Don't call it MD, call it RAID (but not "a RAID", and avoid repeating
"RAID array").

Talking about having the partitions marked makes it sound as if
either it needs to already have been done or you've had someone do
it for you.  Just phrase it in terms of what you should do.

As usual it's fairly pointless to mention partman, since users have no
way of knowing whether they're "in partman" or not.  Just get on with
introducing the menu item they do see.

The "upstream brandnames" (as opposed to the things you'd wrap in
<command> or <package> tags) are all-caps.

You can use it, and it is an option; saying that it can be an option
is overconditionalisation.

You can't expect users to navigate by D-I module names when those
names aren't signposted in D-I.  This particular case is even more
unhelpful, since it mentions the partman menu, then says "The menu"
will appear - but it doesn't mean it'll cause the appearance of the
partman menu, it means the option "Configure software RAID" (which if
chosen will open a submenu)!

(Oh, and there's a missing indefinite article.)

Likewise, mdcfg isn't signposted as mdcfg.  (And none of these module
names is a <command>.)

I don't have any choice about this, but it would be nice if it could
be eliminated from D-I as well.

Don't call it MD, call it RAID.

I might be "issued with" a passport or a gasmask or something, but
it doesn't fit this context.

Don't call it MD, call it... well, call the technology RAID, but
call the instance an array.

Ditto.

Or it might deserve a colon.

Again merging short, choppy, repetitive sentences.

(There are people who would say you can't have "either" of three
things, but I disagree with them.)

Don't call it MD, call it RAID.

Separate numbers and units with non-breaking spaces.

Use words rather than figures for low numbers.

Add an indefinite article in the last line.

(These figures are getting cobwebby - 100 GB looks distinctly cramped
for a home partition these days - but who knows, maybe there's a huge
fileserver on the network as well.)

Don't call it MD, call it RAID, and don't expect users to navigate
by D-I module names.

Plus a few fixes for minor language problems, such as that "return
back" is redundant (and I don't mean the good sort of redundant).