RE: Full documentation for GRUB2

[Leslie Rhorer]

> -----Original Message-----
> From: address@hidden [mailto:help-grub-
> address@hidden On Behalf Of Colin Watson
> Sent: Tuesday, March 29, 2011 11:10 AM
> To: address@hidden
> Cc: address@hidden
> Subject: Re: Full documentation for GRUB2
 
> > >From my experience it's not working to get some newbies or helpers to
> > write docs. It's the developers task and skill to document features.
> 
> Task, perhaps; skill, not necessarily.
> 
> Developers often do not make the best documenters.  We understand the
> software sufficiently well that it's often difficult to remember what
> others don't understand, and thus it's hard to remember to make it a
> priority over other things.

        'Not only that, but having the ability to speak to a machine does
not necessarily imply the ability to speak to another human being.  In the
simplest case, the user and the developer may not have any human language in
common.  While the United States holds the greatest share of both developers
and users, and while the USA is populated mostly by English speaking
individuals, there are many people from both groups whose contribution to
either is significant yet do not speak English.  It is certainly no disgrace
to come from a non-English speaking country.  Even some people who do speak
English well enough, however, are not capable of writing good documentation,
regardless of how close or distant they may be to the subject at hand.  Not
to put too fine a point on it, some excellent code writers are just plain
lousy at technical writing.

        It doesn't help any at all that writing documentation is far less
satisfying and far more tedious than writing code.

> I agree that developers have the *responsibility* to document features
> they add, and I've been trying to encourage this in GRUB where I can.
> However, most of the problem is not new features, but the backlog.
> Occasionally I attack it a bit, but there's a lot to do.

        I sympathize, but only to a point.  No matter how dreary or how
daunting the volume of work, it is essential it be done.

> What I would find really valuable, in addition to documentation patches,
> is *constructive* criticism.  "GRUB's manual sucks" just makes me feel
> demotivated; I might as well do something else rather than bother.
> Pointing out specific things that are unclear or need to be written is
> much better.

        Point well taken.  OK, here is what I might hope is a start:

        The first thing I want to know about any application is what it can
and cannot do.  It's very frustrating to search diligently for a means to
accomplish something only to find in the end it can't be done at all.
Conversely, failing to know something can be done potentially produces
essentially the same result as if the developer had never bothered to
implement the feature in the first place.  In short, simply knowing whether
something is supported by an application or not is half the battle.

        I think a good example of this is the sort order of the items in the
boot list.  Under GRUB legacy, editing the menu list order was quite simple.
I did some significant searching to try to find a way to do this with GRUB
2, but as far as I was able to determine, there is no way to do it.
Eventually I just gave up.  If there is in fact a way, it would have been
really nice for it to be fully documented, but if there were at least a
reference to it being possible, I would not have given up.  OTOH, a
reference to it being not possible would have saved me a fair bit of
trouble, or at least have induced me to request a feature, rather than
fruitlessly searching for one which does not exist.
 
        On a related note, there does not seem to be any way to associate
the default boot selection with a particular target.  To the best of my
ability to tell, one may only specify a specific entry number within the
boot target list, not a specific target.  Thus, if one, for example, has the
third kernel target set as the default and then removes the second kernel
from the drive, GRUB will now point to what was originally was the fourth
kernel.

        Neither of these would have been an insurmountable issue in GRUB
Legacy, but as far as I can tell, they are in GRUB 2.  A simple, relatively
brief list of the features in GRUB2 would be quite helpful, along with
notations of which features are new, which are not, and which are no longer
available would be extremely helpful.

> > I'd like to contribute examples that I found to the grub docs, but the
> > manual gives no hint how to do so... ;-)
> 
> Send patches against docs/grub.texi in GRUB trunk.  If that's too hard,
> send plain-text suggestions and somebody can deal with marking them up.
> 
> Note, though, that GRUB is a GNU project and thus contributions to it
> need to be copyright-assigned to the FSF:
> 
>   http://www.gnu.org/prep/maintain/html_node/Copyright-Papers.html
>   http://www.gnu.org/licenses/why-assign.html
> 
> If you aren't willing or able to do this, it would be better to describe
> your suggestion in general terms so that somebody who's done the
> assignment thing can write something up.  But if you are, we can
> incorporate specific text from you.

        Well, I might also like to contribute in some way, but speaking for
myself, I don't even know where to start.  Knowing where and how to submit
documentation is not really the starting point.  First one must know what
GRUB can do and how one can make it do it.  For those of us who did not
develop GRUB 2, it's rather a chicken and egg problem.