Re: Developer Documentation

[Eric Baudais <baudais okstate edu>]

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.

> So, your effort should be planned as "updating developer.gnome.org".
> It looks like from your list, you are aware of this site - so
> I just want to make sure that the GDP is planning to work on the
> docs there, not create some other resource.

Yes, of course we are planning to update d.g.o, since we have our new
webpages there at http://developer.gnome.org/projects/gdp.
 
> > 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.
 
> > 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.

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.

> > 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?
 
> > libIDL - no docs
> 
> There is an info page with fairly complete docs, though it is a
> bit out of date.

okay.  I don't think that an info page is the correct format for an API
though.  The GDP also wants to migrate all the developer docs to go on
the web using gtk-doc or something similar.  Thanks for the info.