Re: quo vadis, docs

[Alberto Ruiz <aruiz gnome org>]

2009/2/9 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.

Quite true, as a matter of fact, I've been trying to learn how to
write documentation in the latests weeks.

I know nothing about docbook and I like to consider myself sort of a
computer literate, and I'm telling you, my frustration could be used
as a reusable source of energy to power up a whole country at this
point. Why on earth is so hard to learn to create a document with a
few paragraphs and illustrations?

> 3) Make documentation easier to write.  Mallard can help.
> 4) Make it easier to see what documentation needs work.  Pulse
> can help.

What is Pulse? What is Mallard? How can they help?

I've been thinking how hard would it be to have a very basic webkit
based editor that would convert the html it generates into docbook?

Really, good documentation writers are most likely people with no
skills on SVN/DVCS/Docbook/XML whatsoever. We should provide a focused
editor supporting the very basic stuff to write a good GNOME document.


-- 
Un saludo,
Alberto Ruiz