On Sat, 16 Aug 2008 18:42:38 +0200 "John Mandereau" <[EMAIL PROTECTED]> wrote:
> 2008/8/13 Graham Percival <[EMAIL PROTECTED]>: > >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 _______________________________________________ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
