Re: quo vadis, docs

[Tristan Van Berkom <tvb gnome org>]

On Mon, Feb 9, 2009 at 10:36 AM, Luis Villa <luis tieguy org> wrote:
[...]
>> Dan Winship wrote:
>>> Dave Neary wrote:
>>>>> - Should we just ditch the docs and declare the UI self-explanatory ?
>>>> Definitely not.
>>>
>>> Why not?
>>
>> Because (a) the docs are pretty good, merely outdated,
>
> That statement just can't be true. Outdated docs not only don't help
> users, they *actively confuse* users. If they don't help users, and
> actively confuse, they are not 'pretty good' in any meaningful sense
> of the word, since one measures good docs by whether or not they help
> users, not by whether they helped users c. GNOME 2.2, or by how
> comprehensive the confusing coverage is.

What an interesting debate, I will have to drop my 2 cents in the direction
of just letting people know where the docs are useless and confusing and
hope people will not distribute those outdated docs.

Yeah, *some* GNOME projects might have been gifted at one point by
the interest of some corporation writing docs for them - I seriously doubt
that most projects received that attention - from my perspective:
    - Glade user docs were ported from Glade 2, and to this day are still in
      a prototype state.
    - I dont have time to update the website (it was written in raw html,
      and a real pain to update the news just for a trivial release), I already
      made damn sure there was good API reference documentation for
      the libgladeui core - theres no way I'll find time to write cute user
      docs with screen shots.
    - There is no way I could realistically say that one day someone
will write docs
      for Glade - its a promise we simply cant make.

>> and (b) it would
>> send a terrible message about the priorities of the project.
>
> Depends on how you did it. The message could be 'our software is so
> easy to use it doesn't need docs', which is a pretty damn good
> priority. Or the message could be 'we know our limits.' Or it could be
> 'we don't want to insult our users by pretending the docs, in their
> current state, are useful.'

a.) first of all have to agree that pushing outdated user docs as official is
sending a painfully bad message about our internal management (if the docs
are so out of date, why wouldnt all my 'stable' apps crash ?)

and more importantly b.) We cannot allow ourselves to make decisions about
our infrastructure based on what message it sends - at the end of the day we
should only be concerned with what message is sent by GNOME 2.26

Anyway, I'm sure we have great people in our doc team, and if those people
had time, or 10 more people then things would be great - in the meantime
maybe we can at least mark all the outdated documentation as old and obsolete
and at least start an initiative to write user docs for GNOME
applications and the
desktop.

Cheers,
                    -Tristan