Re: Full documentation for GRUB2

[Patrick Strasser]

schrieb Colin Watson am 2011-03-29 19:09:
> On Tue, Mar 29, 2011 at 05:19:09PM +0200, Patrick Strasser wrote:
>> I had a simmilar experience regarding the loopback system
>
> I've committed documentation of this command to trunk.

Thanks! Now that was fast.

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

Sorry, mixed that up. I meant that it is the developers that know about
the features. They know the code from inside out, with all subtleties
and with all the intentions that where the reason to add or change features.

Of course just writing down knowledge does not make a good manual. This
needs skilled writers, which also see the user side and incorporate
issues and use cases that became evident by means of bug trackers or
mailing list request etc.

I regularly read in mailinglists of projects invitations for
documentation writers. Often this reads like "We coders are too
{lazy,busy,uninterested} to write docs, just dig up the source and write
a manual from it".
I'd see it as a two step process: developers document the features, with
intended use cases and reasons; docs writers make a fine manual out of it.

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

GRUB 1 is really great, GRUB 2 is even better. I see that people put
effort in it, and it can do great things. Thanks for the work, and keep up.

I have the impression that GRUB 2 is a very powerful tool. Unfortunately
my impression is that I'm not adept enough to unleash all its powers.

Regards!

Patrick
-- 
Engineers motto: cheap, good, fast: choose any two
Patrick Strasser <patrick dot strasser at student dot tugraz dot at>
Student of Telemati_cs_, Techn. University Graz, Austria