Re: Just shoot me now (was Re: What's wrong with this fancy split?)

[Tommy Kelly <tommy.kelly@verilab.com>]

asjo@koldfront.dk (Adam Sjøgren) writes:

> On Wed, 22 Dec 2010 06:53:07 -0600, Tommy wrote:
>
>> So where does that leave us? 
>
> It is much easier for a developer deep in the code to receive a
> documentation patch...

Totally understand.

> What I am trying to say is that I think you will find much less argument
> if you dig out git and start supplying your suggestions for improvements
> as patches to the manual.

Absolutely agree.

> It is quite natural to say "Meh, but it isn't wrong" if you're asking
> someone to do... the horror... work!

Yep. So just to be clear. I've already begun (and posted to this group)
the beginnings of a rewrite of the bit in question, and I plan to take
that to completion (if I don't shoot myself in the head in the process
:-) ). Lars has pointed me at the git patch  process and I'm aware of
the need for FSF copyright assignment.  

So my questions at the moment are definitely not veiled demands for
someone to fix things for me. Rather they are mostly requests for
information to allow *me* to do the fixing.

> Or the user is trying to achieve to many things at once. There is a
> learning curve, even if you aren't thick ;-)

It's a good observation. In fact, one of the things that tells me that
no matter what else is an issue, the documentation itself could be
improved, is the extent to which simply to do one thing the newbie needs
to dive into so many other things. Of course some pre-requisite
knowledge really is pre-requisite. You can't do physics without
calculus. But sometimes the lower levels are poking through
needlessly. You *don't* need to understand Goedel's Incompleteness
Theorem to do physics, even though it is profoundly important.

Regardless, in many cases I think a bit of extra wordiness in the
docs will allow the new user to get moving faster, thereby helping their
learning when the time comes for them to dive into the guts and,
conversely, lowering the question burden on the experts. Reuse an' all
that :-)

Tommy