Re: quo vadis, docs

[Shaun McCance <shaunm gnome org>]

On Sat, 2009-02-07 at 10:16 -0500, Matthias Clasen wrote:
> - Are we just waiting for some corporate sponsors to pick up the docs
> where Sun left them many years ago ?

Corporate contributions to the documentation team would be
welcome, but picking them up the way Sun did is a band-aid
that will inevitably lead us back where we are right now.

The Sun writers did a lot for our documentation, but they
weren't very active in the community.  When they owned a
document, they updated it without community involvement.
This left us with almost no volunteers who could pick up
the slack when Sun dropped out.

> - Is there anything that can be done, short of transmutating hackers
> into technical writers at next guadec with the help of poisoned beer ?

Steps that would help:

1) Make it easier to run the latest development version.  I got
myself set up for working on 2.25 documentation yesterday, in
part to review your patches.  It took me most of the day Sunday
just to get 2.25 in front of me.  And I'm a programmer.  Most
potential writers are not.

2) Provide better documentation for how to write documentation.
The GDP Handbook is outdated and overwhelming.

3) Make documentation easier to write.  Mallard can help.

4) Make it easier to see what documentation needs work.  Pulse
can help.

5) Ensure the community can respond to potential new members.
This means that either I have to have a lot more free time, or
we need more trusted community members alongside me.  The former
doesn't seem likely, and the latter is kind of a Catch-22.

In my experience, (1) and (5) have been the biggest problems.
People grumble about the other three, but they usually manage
to figure it out.

--
Shaun