Re: quo vadis, docs

[Luis Villa <luis tieguy org>]

On Mon, Feb 9, 2009 at 11:39 AM, Matthias Clasen
<matthias clasen gmail com> wrote:
> On Mon, Feb 9, 2009 at 11:17 AM, Luis Villa <luis tieguy org> wrote:
>
>>
>> [1] I'm taking for granted that there are in fact no bug reports; I
>> really don't know and haven't looked in a long time, though certainly
>> virtually no reports were filed about docs by regular users when I was
>> active.
>>
>
> There are a couple of gnome-user-docs bugs complaining about some of
> the things I listed. I don't know if they were filed by 'regular
> users'.

FYI, I emphasized 'regular users' since reports by the doc team, while
useful, are not indicative (one way or the other) about usage
patterns.

> Anyway, a simple alternative to a prolonged discussion about dropping
> docs and similar drastic measures is to just chime in and help making
> GNOME 2.26 the "best documented GNOME since 2.2".
>
> I have done patches for about half the problematic capplets this
> weekend. I'm sure if some more people are willing do update one
> section each, we can have 100% accurate docs by the end of the month.

+1 to that solution! :)

> As Jon McCann pointed out to me, sitting down and trying to write docs
> for a piece of software is a valuable excercise for developers, since
> it teaches you just how bad some of our UIs are...

Amen. I've often felt developers should be required to document their
own UI changes :) Heck, simply asking 'what does this dialog mean'
would be useful a lot of the time...[1]

Luis

[1] ahem: http://tieguy.org/screenshots/terrible_dialog.png