Re: Developer Documentation

[Owen Taylor <otaylor redhat com>]

Eric Baudais <baudais@okstate.edu> writes:

> Owen Taylor wrote:
> > 
> > Eric Baudais <baudais@okstate.edu> writes:
> > 
> > > Hi all-
> > >
> > > I have been asked by Dan Mueth (GDP's fearless leader) to compile a list
> > > of all the documentation currently available for GNOME developers.  It
> > > is our (GDP's) hope that we can rearrange the current documentation so
> > > it is in a more central location and easier to find exactly what a
> > > developer needs in a timely fashion.  In other words, making the docs
> > > easier to find the correct information than looking directly at the
> > > code.
> > 
> > It's great that you are working on this. I will point out that
> > we have a central location for GNOME developer documentation
> > with quite extensive resources and (IMO) good organization:
> > 
> >  developer.gnome.org
> 
> hmm, d.g.o is not really organized that well.  You have the docs
> organized by what they are: tutorial, whitepaper, HOWTO, etc. and not by
> what they cover.  The docs should be organized by what they cover:
> ORBit, gnome-libs, bonobo, gnome-print, etc.

d.g.o has both. The architecture section contains links to all
the documents relevant to a particular area. It possibly should
be placed a bit more prominently.

Multiple navigation technqiues is the general way to do things.
 
> > > ORBit-Perl binding - general doc
> > 
> >  (I'm not sure what you mean by "general doc".
> >   http://people.redhat.com/otaylor/corba/mapping.html is a non-obvious
> >   resource.)
> 
> Well, there is not enough docs on ORBit language bindings and if I can
> find it in 2 minutes, it really is an obvious resource, IMHO.

? I was just trying to give you something for whatever list you
were making up.... If you found it, good.

> > > gtk+-1.2 - API docs, tutorial
> > > gdk - API docs
> > 
> > GTK+ tutorial covers both GDK and GTK+. GGAD is a useful resource.
> 
> yes, but the GTK+ tutorial is mainly over GTK+ and only interjects GDK
> when it's necessary to the information pertaining to GTK+ widgets and
> their operation.  There is no tutorial mainly over GDK, just hints here
> and there.

A tutorial on GDK wouldn't really make sense. You can't meaningfully
use GDK without GTK+. The "Scribble" section of the GTK+ tutorial
contains fairly extensive information about GDK.
 
> I also hope that someone will take the time to write another GGAD over
> gtk+-1.4 and glib-2.0 when they are about to be released as stable
> libraries.

GTK+-2.0 and GLib-2.0. Havoc has plans to eventually update GGAD for
the GNOME-2.0 platform. 

(I'm also working on book about GTK+ with Tim Janik and Ian Main, but
since it is, at this time, conventionally licensed it's not really
relevant in a list of free documentation.)
 
> > > libunicode - no docs
> > 
> > A dead library, not really part of the GNOME platform. (It may
> > be used by a few things in GNOME-1.4, but it is unmaintained
> > and being replaced by unicode functions in GLib-2.0)
> 
> okay.  Do you know of anyone starting on documentation for glib-2.0?

The RDP should be turing its efforts to GLib-2.0 soon. GLib-2.0
in general, isn' very different from 1.2, except for the addition
of GObject. (Which I'm trying hard to get Tim to write docs for.)

Regards,
                                        Owen