> -----Original Message----- > From: help-grub-bounces+lrhorer=satx.rr....@gnu.org [mailto:help-grub- > bounces+lrhorer=satx.rr....@gnu.org] On Behalf Of Colin Watson > Sent: Tuesday, March 29, 2011 11:10 AM > To: grub-devel@gnu.org > Cc: help-g...@gnu.org > 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. _______________________________________________ Grub-devel mailing list Grub-devel@gnu.org http://lists.gnu.org/mailman/listinfo/grub-devel