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

[Murray Cumming <murrayc murrayc com>]

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.

> 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.

> 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:

I'll try to chase up the relevant maintainers about these documents, in
a week or so, if nobody else does.

> > * 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.
> 
> 
> 
> 
> _______________________________________________
> gnome-web-list mailing list
> gnome-web-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-web-list
-- 
murrayc murrayc com
www.murrayc.com
www.openismus.com