Re: proofreading the installation-guide
Hello,
On to spending some time on answering this...
Justin B Rye, le Sun 26 Jul 2015 13:15:18 +0100, a écrit :
> 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.
Possibly not. I don't think it matters very much, though.
> 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.
> * 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.
> * 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.
> (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.
> * 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.
> * <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).
> * 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.
Samuel
Reply to: