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

[Graham Percival]

On Sun, 17 Aug 2008 22:34:20 -0400
Kieren MacMillan <address@hidden> wrote:

> Hi Graham,
> 
> I agree with *most* of your post here___ except
> 
> > I honestly think that stopping the doc team from disintegrating
> > is more important than nice new features like that.
> 
> Depending on the feature, this can be *far* more important than  
> having one person stay with the doc team.

I'm not saying that doing a 2-hour feature is bad, but I *definitely*
disagree that losing somebody from the doc team isn't cause for serious
concern.

Let's suppose that we need a critical mass of 3 "full-time" doc
writers ("full-time" meaning "normal open-source time", ie 5-10
hours a week, including mailist reading) and 1 "full-time"
technical person.  By "critical mass", I mean that this spreads
the workload enough, there's enough people reading new doc work
such that the doc writers don't feel useless, and there's enough
technical aid that the doc writers don't get overly frustrated
with technical problems that arise.

I think that's a reasonable estimate.  Now let's assume that at
any given moment in time, one person might be away on a vacation,
and another person might be overwhelmed with work (be it composing
deadlines, marking coursework, writing journal papers, whatever).
So we now need a doc team of 5 writers and 1 technical person.

If Carl and Trevor started fixing bugs full-time, we'd have less
than 5 writers.  Would this instantly make the doc team implode?
No, of course not.  But Jonathan is a professor; it's reasonable
to suppose that in Nov he might drop out for a month to practice
for concerts, rehearse student ensembles, publish papers, or
whatever he does.  (I can't remember if he's performance,
composition, theory/history, or what)

Come to think of it, Francisco is *also* a professor.  Let's say he
also drops out in Nov in order to grade student compositions before
their big Dec concert.  And/or decides that he should work on the
Spanish transations instead of rewriting Vocal.itely.

Now we're left with 1-2 doc writers.  If it's only for one month,
they'll probably still be around... but if there's only 2 doc writers
for a longer period of time, at least one of them will get fed up with
trying to keep up with the entire docs.  Repeat this process a few more
times, and in a year or two the doc team will be gone.


This wouldn't be a problem if we had a steady (even if slow) stream of
new people getting involved in the docs, but that's unlikely to happen
-- other than LSR, which hasn't been taking off, new contributors need
to learn git+texinfo before they can even *start* doc writing.

I'll admit that I wouldn't be so pessimistic if GDP had actually
finished the rewriting... and NR 1+2 will *probably* be finished by the
end of 2008.  If the docs are in good quality, I guess that 1-2 doc
writers are enough to keep maintaining them.  As long as the current
team doesn't disintegrate for six-twelve months, I guess things are ok.


I still really, really wish that normal users would answer more
questions, more quickly, so that people who *have* spent the 5 hours
learning git+texinfo (plus another 2-3 hours learning the documentation
style) can spend more time putting those skills to work.

I also wish that advanced users would contribute more to LSR; the whole
point of that infrastructure was to allow people to help a bit with the
docs without having to spend the 5-10 hours learning the ropes.

Cheers,
- Graham