Re: GNOME documentation

[Havoc Pennington <hp redhat com>]

On Fri, Jan 31, 2003 at 01:33:55PM +0100, Chris Parker wrote:
> I started a long email about what I think is wrong with the GNOME
> documentation, but I saw there was pretty much a common theme in what I
> was going to say.  Are there any plans for making more cohesive,
> functional documentation ala http://www.php.net?  I am a Unix developer
> who would really like to use Gtk and/or GNOME libs on HPUX but I can't
> leave around code for developers that might come behind me with the
> documentation in the state it is in.

There are various people that work on evolving gtk-doc and improving
the doc system, there's a gtk-doc-list you can join at:

  http://mail.gnome.org/mailman/listinfo/gtk-doc-list/

The GTK docs in fact have a lot of good information and almost all
functions are documented. The signals are often not covered; making
gtk-doc report missing signal docs in the doc status percentage would
be useful.

The organization could frequently use love as well, for example the
index of functions is above the overview sections, and often people
don't see or read the overview section as a result.

e.g. there are several examples of GtkMessageDialog but you have to
scroll down:

  http://developer.gnome.org/doc/API/2.0/gtk/GtkMessageDialog.html

For the widgets with lots of methods, people don't scroll down and
find that stuff.

There are also overview/index sections people don't find:

  http://developer.gnome.org/doc/API/2.0/gtk/ch01.html
  http://developer.gnome.org/doc/API/2.0/gtk/TextWidget.html

The FAQ on gtk.org should be merged with this part of the manual and
brought more up-to-date:

  http://developer.gnome.org/doc/API/2.0/gtk/gtk-question-index.html

And the tutorial needs to be brought up to date and improved.

Re: your question "are there any plans?" - the way open source works
is that specific things happen only if you do them. ;-) If you don't
contribute, then lots of *stuff* will happen, but it won't necessarily
match what you would like to see. If you do contribute, you get to
decide what gets done. There's no real way to predict what will
happen, other than what people are already working on; people slowly
evolve the GTK+ docs but I don't know of any large-scale or massive
overhaul efforts currently in progress.

Havoc