Re: quo vadis, docs

[Stefan Kost <ensonic hora-obscura de>]

hi,

Shaun McCance schrieb:
> 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.

Also asciidoc (http://www.methods.co.nz/asciidoc/) looks promissing to me. One
can write a document in a kind of wiki markup and asciidoc can producs html or
docbook from it. Thanks to wikipedia people are used to wiki markup.

One thing that is missing to be able to edit the source on a click and submit a
patch.

Stefan

> 
> 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
> 
> 
> _______________________________________________
> desktop-devel-list mailing list
> desktop-devel-list gnome org
> http://mail.gnome.org/mailman/listinfo/desktop-devel-list