Documentation [Was: The community has lost control... (Was: Re: Don't put new packages through updates-testing)]

[Jonathan Underwood]

Hi,

I have been following the thread about the slightly chaotic F7 changes
to infrastructure etc, and there seems to be agreement on one thing -
much of the problems that the community faced stemmed from a lack of
communication from the people making the substantial changes and the
rest of the community. The rest (or a large part)  of the community
then perceived breakages and work flow hinderance and got upset and
confused.

On the positive side, the turnover during F7 was phenomenal and I am
sure that the benefits outweigh the disruption by orders of magnitude.

But the great news is, it's not too late to really make the most of
this. What I believe is needed is a week of consolidated documentation
writing. We need the barrier to contribution to Fedora to be orders of
magnitude below where it is currently (and it was raised by several
during the F7 process due to lack of documentation).

So; here's my proposal. Everyone stop non-critical packaging work for
a week and write some damn docs and really make the whole packaging
and building processes transparent. I have no doubt that people
intimately involved with the infrastructure changes are reading this
and thinking "but it's all pretty obvious". Well, it is if you've been
spending 8 hours a day for weeks working on it. ;)

I actually started looking to do this and realized what a mess the
current docs are in. Most of the important docs are squirreled away as
drafts or personal FAQs. Nothing is finished. It's far too much work
for one person.

ASIDE: I'm also not convinced that the wiki platform we're using is
actually conducice to writing good documentation. It's great for low
entry for writing a single page, but it's rubbish for putting together
a coherent set of docs. Is there something better we can look at using
in the long term (not NOW though, priority number one should be
getting some pages written)

Anyway, that's my rant.

jonathan