Re: gnome-devel-docs: Some candidates from d.g.o.

[Shaun McCance <shaunm gnome org>]

On Wed, 2007-09-05 at 11:17 +0200, Murray Cumming wrote:
> On Tue, 2007-09-04 at 14:23 -0500, Shaun McCance wrote:
> > On Sun, 2007-09-02 at 20:19 +0200, Murray Cumming wrote:
> > > developer.gnome.org has some stuff that still relevant but isn't
> > > elsewhere. It's rotting away and isn't convenient for library.gnome.org.
> > > 
> > > Here is a list of what I've found so far. They could be added to the
> > > gnome-devel-docs module. If any of them are horribly updated then we
> > > should probably just remove them altogether. I guess we should reply to
> > > parts of this CCing the document authors and relevant module
> > > maintainers, to discuss it.
> > 
> > It might be useful to have a taxonomy for documents.  Here's
> > a rough one off the top of my head.  Documents are classified
> > according to three criteria: target, interface, and stability.
> > 
> > Target:
> >   Either a specific piece of software (e.g. GTK+, GStreamer,
> >   Nautilus) or a group of software (e.g. Platform, everything)
> 
> Yeah, I suppose, though this is probably fairly obvious now.
> 
> > Interface:
> >   External (e.g. developing against GTK+, developing Nautilus
> >   plugins), or internal (e.g. hacking on Nautilus itself)
> 
> Yeah, though anything that's platform is external, and anything that's
> non platform is at least semi-internal: It should only really be used by
> a very few tightly-bound applications.

Well, what I meant by internal was that it documents interfaces
that are never used outside of that software.  For instance, I
could write a document about the transformation infrastructure
in Yelp.  The only reason you'd want to read this is to work on
Yelp itself (or to fall asleep at night).  You could write an
internal document for a platform library as well.  I suppose
that stability really only applies with external documents.

> > Stability:
> >   Platform (very rigid stability guarantees), stable (not in
> >   the platform, but tries to make the same guarantees), or
> >   unstable (can change on a whim)
> 
> Let's just keep the Platform, Desktop split that is already defined by
> the API rules/guarantees for these two release sets. And let's keep
> anything out of gnome-devel-docs that isn't part of the platform. I
> think there would be much room for confusion if it contains
> non-API-stable stuff.

I don't think it's quite that simple.  In fact, much of the
information in gnome-devel-docs right now is about things
that we don't consider platform-level stable API:

Platform Overview:
  The Platform Overview talks about basically all the libraries
  that are useful, including desktop libraries like GStreamer
  and external libraries like Avahi.  But it does avoid widget
  collection libraries like eel.

Integration Guide:
  The Integration Guide talks about "interfaces" other than
  functions defined in a library.  It tells you how to deal
  with desktop files, icons, MIME types, etc.  These are APIs,
  but they're not APIs provided by some package.  I have no
  idea what the stability guarantees are on these.

I don't think we want to cut all that information out.  If
we did, the Platform Overview would be far less interesting
(and useful), and the Integration Guide wouldn't exist.

--
Shaun