Re: it's all up to you users (was: Please forget LM MG NR IR SL AU)

[Graham Percival]

On Sat, 16 Aug 2008 18:42:38 +0200
"John Mandereau" <address@hidden> wrote:

> 2008/8/13 Graham Percival <address@hidden>:
> >It's a waste because, 7 days from now, there will be precisely
> > half a dozen people who are updating the documentation.  There's
> > at least 50 people who can answer simple questions here.  To be
> > efficient, those six people should spend their time updating the
> > docs -- better docs help everybody in the future, whereas writing
> > a detailed and polite email only helps one or two people right
> > now.
> 
> Why not doing both?

Because it's impossible to do both at the same time.  It takes
time and energy to answer emails or write docs.

That seems trivial -- surely everybody knows this already -- so
let's discuss a specific example.  I'll pick on Valentin since he
won't mind... and also since he's almost a complete opposite of
me.

He offered to do NR 1.8 Text last Jan or Feb.  It's still not
finished.  text.itely would be a 5-hour job for me, so I figured
10 hours for GDP helpers.  Granted, he's working on a foreign
language.  If I had to write text.itely in French, it would
probably take me double the time -- *only* double, despite my very
poor French, since most of the docs are in examples anyway.

So let's call it 20 hours.  Was it really impossible for Valentin
to find 20 hours to work on the docs in the past 8 months?

Obviously not; he's probably spent **ten times** that amount of
time on lilypond.  The lilypond report #10 (the algorithmic
composition special edition) probably took more than 20 hours just
for that single issue!  Add in all the bug handling, LSR stuff,
English and French mailist, maybe translating, and there's a huge
amount of volunteer effort there.

But the question that I keep on coming back to is this: is that
enormous effort being spent in the best way possible?


GDP is ending with a half-finished NR 1.8.  It's also ending with
a half-finished NR 1.6; Text isn't the only unfinished "main
notation" section.  Lots of users don't read the mailists; they'll
just see these unfinished doc sections.  For the sake of argument,
suppose that Valentin could have finished NR 1.8 if he had only
answered half the emails that he did.  Wouldn't that be a good
trade-off?

There's also some trickle down effects to consider.  I've told
some doc helpers *not* to get involved with programming (or at
least to restrict their efforts in this direction) so that we
retain an actual "doc team".  If we have 6 people working on the
docs, they can share the load, comment on each other's work, and
generally bolster each other's morale.  If we only had 2 or 3
people working on the docs, the strain on each person becomes much
larger.

If we had more people in the doc team, then I wouldn't have
discouraged Carl from doing programming -- we could have people
moving from advanced docs to bugfixing without putting the doc
team in danger.


Why does this matter to Valentin?  Well, remember that
\includerelative "foo.ly" command that we desperately wanted?  He
even offered a bounty for it?  I'm willing to bet that Carl could
implement that feature in 1-2 hours.  It requires a mixtures of
C++ and scheme, but I think he has the necessary skills.

However, I honestly think that stopping the doc team from
disintegrating is more important than nice new features like that.
The doc team might disintegrate if there aren't enough people
working enough on the docs.  There won't be enough people working
enough on the docs if helpers keep on writing long, polite emails
to clueless newbies who haven't read LM 3.


Obviously there's a trickle-down effect for answering questions.
I estimate that about 1 in 20 people asking a question on -user
will start answering questions for other people.  And
approximately 1 in 10 of *those* people will start contributing
patches (either docs or bugfixes).

My hope is that LSR will reduce the latter number to 1 in 5 or so.
I was really hoping that this "it's all up to you users" would
reduce the 1 in 20 figure as well, but given the complete lack of
users saying "you've made some good points.  Sign me up to be on
the Fuzziness Force.  I can't answer a lot of questions, but if I
see any question that I *can* answer, I'll do it", I'm not
optimistic.


As a general rule of thumb, I think that (for maximum benefit for
lilypond), everybody should try to work on material that's
slightly too hard for them.  New users should answer RTFM
questions.  Moderately skilled users should submit LSR stuff and
make suggestions for the docs.  Advanced users should write docs,
edit LSR snippets, or work on bugfixes and new features (in based
on scheme, such as Rune's twelve-tone accidental stuff).

Of course some jobs just don't appeal to some people.  If you
don't have the patience to write docs, then work on specific LSR
snippets or bugfixing.  If scheme makes your eyes glaze over, try
to improve LM 3 or work on an untouched NR 2 section.  Etc.

But if you *are* an advanced user -- especially somebody who knows
git and texinfo -- and you spend a lot of time writing emails, I
think it's worth asking yourself if it's really the most effective
use of your time.


I'm not saying this because I don't care about new users -- after
all, the whole *point* of documentation is to help users -- but
rather because I know that Valentin's concerned about the general
well-being of the project.  And I'm concerned about Valentin
spending so much effort.

I'm infamous within my research group for being a "no-man".  In
English slang, a "yes-man" is somebody who always agrees with his
boss.  They're great for making his boss feel good (and tend to be
promoted because of this), but if the boss has a terrible idea,
they'll praise it anyway.  In contrast, my first instinct is
always to look for problems and find reasons why something won't
work.  It doesn't make people feel nice, but being a "no-man" is
best for the organization in the long term.


> >  And who really cares how busy the programmers and doc
> > writers are?  I mean, that's the whole point of open source,
> > right?  The users get free software, documentation, and email
> > support.
> >
> Exactly, but users don't get all the features and support they want
> for free.  Some features nobody wants to add for free, or  dedicated
> user support might be sponsored.

Err, maybe this didn't translate over text and language.  That was
me being bitter and sarcastic.  IMO, users *shouldn't* expect free
email support.  And they certainly shouldn't complain about the
support they get.


> > As I said, I've tried polite recruitment.  Take a look at the email
> > archives; probably about six, twelve, and eighteen months ago.  It
> > seems to have worked for doc writers, but it hasn't worked for
> > finding (and keeping) -user support people.
> >
> On the French list, we never had to recruit people to provide support,
> users who recently discovered LilyPond help each other, developers and
> advanced users reply only if necessary (I expect somebody is going to
> shoot me for all unreplied messages there :-p).

Is this lilypond-user-fr?  It looks like a very low-traffic list.

Cheers,
- Graham