Re: Full documentation for GRUB2

[Colin Watson]

On Tue, Mar 29, 2011 at 05:19:09PM +0200, Patrick Strasser wrote:
> I had a simmilar experience regarding the loopback system - which is by
> itself really great. The manual gives a hint of the command, but no
> description and no example. I got some working examples from Ubuntu
> [ubuntu] and from pendrivelinux.com [pendrive:0][pendrive:1], but no
> documentation.

I've committed documentation of this command to trunk.

2011-03-29  Colin Watson  <address@hidden>

        * docs/grub.texi (loopback): New section.

13.3.25 loopback
----------------

 -- Command: loopback [`-d'] device file
     Make the device named DEVICE correspond to the contents of the
     filesystem image in FILE.  For example:

          loopback loop0 /path/to/image
          ls (loop0)/

     With the `-d' option, delete a device previously created using this
     command.

> >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.

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.

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.

> 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.

-- 
Colin Watson                                       address@hidden