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

[Shaun McCance <shaunm gnome org>]

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)
Interface:
  External (e.g. developing against GTK+, developing Nautilus
  plugins), or internal (e.g. hacking on Nautilus itself)
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)

Documents in gnome-devel-docs should generally be
  {some group, external, platform | stable}

Per-software documents should be included with said software.
As for internal or unstable documentation, it might be worth
having a hacking-gnome-docs package.  Then again, that sort
of information might be better off on the wiki or the mythic
new CMS-managed gnome.org.

On with the show:

> * GNOME HIG:
> http://developer.gnome.org/projects/gup/hig/
> in svn here:
> http://svn.gnome.org/viewcvs/web-devel-2/trunk/content/projects/gup/hig/
> This is already docbook. There's a lot of other build crap there, but I
> think most of it doesn't work anyway. If it was a simple docbook
> document in a regular module then it would be much easier to keep it
> up-to-date.
> Shaun seems to be doing this right now, which is great:
> http://svn.gnome.org/viewcvs/gnome-devel-docs/trunk/hig/

This has now been put into the build, so you'll be able to read
the HIG in Yelp in Gnome 2.20.  I *think* library is supposed to
pick it up automatically now that it's in the build, but we may
have to move the special-case link-to-the-web HIG rule out of
the way.

> * Nautilus Internals:
> http://developer.gnome.org/doc/whitepapers/nautilus/nautilus-internals.html
> in svn here:
> http://svn.gnome.org/viewcvs/web-devel-2/trunk/content/doc/whitepapers/nautilus/
> It's HTML so it would have to be converted to Docbook. I worry that this
> is not part of the Platform, so it's not API that we should be
> promoting. Maybe we need a gnome-desktopdevel-docs (or better name).

This is internal, per-software documentation.  It should live
inside Nautilus.

> * Optimizing GNOME Software:
> http://developer.gnome.org/doc/guides/optimisation/
> in svn here:
> http://svn.gnome.org/viewcvs/web-devel-2/trunk/content/doc/guides/optimisation/
> It's actually three documents, but they could be combined. I guess that 
> it needs to be updated. Federico probably has opinions about that.

An optimization guide would be very welcome in gnome-devel-docs.
If anybody wants to take on the task of combining that information
into a single DocBook document, I'll gladly host it.

> * L10N Guidelines for developers:
> http://developer.gnome.org/doc/tutorials/gnome-i18n/developer.html
> in svn here:
> http://svn.gnome.org/viewcvs/web-devel-2/trunk/content/doc/tutorials/gnome-i18n/
> It's html. There seems to be some conflict with the i18n guide that is
> already in gnome-devel-docs:
> http://svn.gnome.org/viewcvs/gnome-devel-docs/trunk/tutorials/i18n/

The old i18n guide in gnome-devel-docs isn't included in the build.
I absolutely want a document detailing how to internationalize your
software in gnome-devel-docs.  Perhaps we can combine the best of
whatever content is available and clean it up.

> * Creating a Metacity theme:
> http://developer.gnome.org/doc/tutorials/metacity/metacity-themes.html
> in svn here:
> http://svn.gnome.org/viewcvs/web-devel-2/trunk/content/doc/tutorials/metacity/
> It's html. Maybe we could get that into metacity instead so it can be
> uploaded to library.gnome.org?

This is per-software, external.  It's basically in the same class
of documents as "writing a plugin for foo".  It should live inside
Metacity, I think.  But it would be great if we had a section on
library for these sorts of documents.

> * Writing panel applets:
> http://developer.gnome.org/doc/tutorials/applet/index.html
> in svn here:
> http://svn.gnome.org/viewcvs/web-devel-2/trunk/content/doc/tutorials/applet/
> It's HTML.

This should probably live inside gnome-panel.  I'm not so sure
on categorizing it though.  While it could be considered to be
a plugin-writing guide, I think most people generally think of
panel applets as more desktopy than just plugins for something.