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

Re: Grub Manual



On Thu, 18 Oct 2007, Jacques B. wrote:

(... snip of GRUB documentation ...)

> Based on that I have to conclude that what Karl stated isn't
> necessarily incorrect (my apologies).  It did lack some
> clarification differentiating between grub's root file system vs the
> OS root file system.  However Karl was not correct through knowledge
> of this, but rather by accident.  He was of the opinion that
> anything that was on its own partition had a root and could be
> properly referred to using that term...

this is, i believe, the fundamental downfall in pretty much all of
karl's submissions to this list.  on any topic, his *initial* post is
semantically incorrect and, only after much howling and shrieking, do
we learn that he was simply redefining commonly-understood
terminology.  in a funny way, we eventually come around to the
realization that karl (kind of, sort of) actually understood what he
was talking about, but he butchered the explanation in such a way as
to make his "tutorial" on the topic not only worthless, but in some
cases actually dangerous.

your problem, karl, is that you simply have not come to grips with
what makes documentation worth anything, and that's that it use
precise and universally-understood terminology in a consistent way.
and you just don't do this.

in one case, you describe GRUB as "the tiny software that let us boot
our Linux or Windows operating systems".  the "tiny software"?  where
did that expression come from?  and what is its value in your alleged
explanation.  in that same posting, you don't even use the phrase
"boot loader".  under the circumstances, what value can your
documentation possibly have?  how can you possibly claim to be
improving the documentation for GRUB without describing it as a boot
loader?  the mind reels.

you do the same thing in redefining the well-established phrase "the
root directory" to mean the root directory *of a given partition,*
without warning the reader that that's what you're doing.  that's
simply confusing and potentially dangerous.

let me emphasize this as strongly as i can, karl -- it doesn't matter
if *you* understand something.  what matters is that what you *write*
is correct and precise, and that's what's missing entirely from your
postings.    your terminology is, in a nutshell, unacceptably sloppy.

i'm begging you, karl, take this advice from someone who has been
writing technical documentation and tutorials for years and still
thinks there's always room for self-improvement.  as a (sort of
self-promoting, whorish example), i have a new web site and i've
started a little wiki where i'm throwing together little HOWTOs (yes,
the site is still a bit disorganized, i'm working on it in my copious
free time. :-)

here's one HOWTO -- how to write, build and load a trivial kernel
module:

http://www.crashcourse.ca/wiki/index.php/Writing_your_first_kernel_module

now, if this HOWTO is going to have any value, it has to be absolutely
correct and use the same terminology that everyone else understands.
if either of those is false, then what i've published is worthless
crap.  see how that works?  it doesn't matter if *i* understand how to
write and load a simple kernel module -- what's crucial is that i get
that information across to the reader.  when it comes to
documentation, nothing else matters.

at the moment, karl, i think it's safe to say that almost no one takes
your postings seriously, and that's only because you've thoroughly
destroyed whatever credibility you ever had.  but there are two
solutions to that.

on the one hand, you can take the advice of numerous members of this
list and start your own blog.  if you do that, and write good
documentation, then people will come and read it.  if it's bad
documentation, people *won't* read it.  it's as simple as that.

on the other hand, if you're truly determined to write documentation
for fedora, then you should consider joining the fedora docs project
here:

  http://docs.fedoraproject.org/

but (and let me stress this part ... *BUT*) if you do that, then you
need to be prepared for criticism, and understand that, if someone
rejects your submissions, it's probably because those submissions are
not good enough, and *not* because everyone else at the fedora docs
project is stupid.  you have a bad habit of not considering the first
possibility, and immediately leaping to the second.  and that's going
to make your membership in any documentation project very short
indeed.

it's up to you, karl.  you can actually listen to what folks on this
list are telling you and become a productive generator of helpful
documentation, or you can continue being a stubborn, pig-headed
irritation to the entire membership.  the choice is yours.

rday

P.S.  for anyone who might be interested, i'm now a (the?) official
maintainer of the Linux Kernel Module Programming Guide for the 2.6
kernel here:

http://tldp.org/LDP/lkmpg/2.6/html/index.html

and i plan on doing some major updates in the near future.  if you
have any cool topics that you think should be added, i'm all ears.

-- 
========================================================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry
Waterloo, Ontario, CANADA

http://crashcourse.ca
========================================================================


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