Re: proofreading the installation-guide
Samuel Thibault wrote:
> On to spending some time on answering this...
Well, you may have noticed I'm rather taking the long view on actually
getting started on stage one.
> Justin B Rye:
>> 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.
>
> Probably just lack of coordination between manual contributors. Cleaning
> up probably welcome indeed.
So maybe this is the place to start, if I can produce a patch fully
implementing the idea to go with my bugreport.
>> * 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?
>
> Probably because it's called md in the linux kernel.
Yes, that would explain how the mistake came to be made, but it's
worth noting that even the kernel documentation for it (aimed at the
most hardcore of techies) has always explained it in terms of RAID.
Section 6.3.3.4 "Configuring Multidisk Devices (Software RAID)" might
want to mention "md" somewhere, but not in the title - all that's
really needed is a footnote explaining why the tool for setting up
RAID is called mdcfg.
(And since that isn't even true anywhere outside D-I, in a sane world
we'd simply rename that module to "raid". But that would require much
more than just documentation patches.)
>> * 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);
>
> I agree that this is confusing because the intuition of most people will
> be the converse of what is meant. It's however not only in the manual
> that it needs to be fixed, but also in the installer itself.
And it can be traced back to debconf, which uses a template named
"debconf/priority" when what it means is "debconf/filtering". But
fixing that would cause havoc for every preseeding setup in existence,
and probably every installed system with a debconf database. It's
about as likely to be fixed as the misnomer "templates".
I'm currently looking for a way of patching over it in the
documentation, but I'm not getting very far.
>> (Perhaps I should make these three separate bugreports?)
>
> To classify discussion, that may help, yes
>
>> (In fact, maybe the answers are or should be in a README somewhere?)
>
> Probably. The doc folder already has some information, additions is
> welcome.
Actually I'd missed the doc folder in my svn checkout, which doesn't
help!
>> * Structure - some of the XML files seem to be unused relics, but
>> it's hard to tell which...
>
> There is the svn version it is based on at the top of each of them.
Looking at datestamps would flag the "What is Debian" page as
unmaintained, while the subpages giving tips for Linux 2.2 on PDP-11
or whatever would escape my notice as long as they keep getting
affected by global search-and-replace operations.
All I want to do is search for filenames that are never referenced in
other pages, but I need a version of grep that ignores commented-out
text...
>> * <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"?
>
> It depends on the context. When it is about the software in general, it
> should be the official name, which is GRUB. When it's a command to type,
> then <command>, when it's a package to install, then it's <classname>
> (not classinfo, apparently).
Oh, yes, sorry, I don't know where I got "classinfo" from. But I know
why I failed to remember "classname"!
It's not immediately obvious why we're going to the trouble of
distinguishing <command> from <classname> (along with <filename>,
<prompt>, <literal>, and who knows what else). I'm sure it's all
lovely and semantic, but all we actually want is for them to be
flagged as verbatim literal strings by appearing in the same
nonproportional typeface.
>> * Should all <title>s be titlecase? Could we switch to sentencecase?
>
> A lot of people contributing to the manual are not native english
> speaker, that's probably why the casing :)
>
> I personally don't really mind, but I will probably always forget to
> stick to titlecase, if we choose that.
I thought for a while that we were trying to follow a rule of
"titlecase for main titles, sentencecase for subtitles", but no, it's
just slightly random.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: