Re: A starting proposal for library.gnome.org

["Curtis C. Hovey" <sinzui cox net>]

On Mon, 2003-11-10 at 02:51, James Henstridge wrote:
> On 10/11/2003 1:13 PM, Curtis C. Hovey wrote:
> 
> >I've reviewed the content of developer, www, and foundation sites, and I
> >put this proposal together for the libraries top level sections.
> >
> >Almost every section will be organized into editions, with an index page
> >that will direct the user to the different editions.  What constitutes
> >an edition is driven by the section's content.  The index page will
> >emphasize the current edition, and the links to the current edition are
> >static; current maps to the most recent edition.  I believe that in he
> >case of old  editions like, API's, the page must indicate the content is
> >obsolete, something in the style perhaps so that the content isn't
> >revised.
> >  
> >

> Out of interest, what is the rationale for putting all this content on a 
> new website?  Appart from the press releases and case studies and 
> foundation related documents, it sounds a lot like our existing 
> developer.gnome.org site.  Would it really be easier for people to find 
> the Foundation charter or the latest Gnome press release on a 
> "miscelaneous documents" website than where they are now?

I may be going to far.  Jeff and Glynn may explain the plan better than
this.  Glynn is out to overhaul d.g.o, tossing out the cruft and
consolidating the remaining.  Jeff wants to tightly focus d.g.o on the
gnome developer community, and move the documents to library.gnome.org.
d.g.o's content could be merged with w.g.o in the future.

If the sites are unified, then it seams natural to explore putting
w.g.o's documents into the library.  The w.g.o and f.g.o documents are
written for their respective audiences, so they do seem out of place in
a library dominated by technical documents.  If there is little
crossover for the material, I'm not inclined to merge them into the
library.

Merging two site may present filename collisions, and like the library,
if there two audiences don't share a lot of tasks, the site should
remain separate.  I posted a list of use cases a few weeks ago to this
list to help focus the direct of developer, foundation, and www.

Merging the site's might be nothing more than refining the navigation to
direct users to the best material on other GNOME domains.

> There are some good ideas in here that I agree with though.  Putting 
> some version info into the URLs should help with the long term 
> maintainability of the website.

Permanent URLs, managed growth, and serving the users are the goals.

> Marking obsolete content as such sounds good (as opposed to removing it, 
> or leaving it untouched).  A notice like this should be obvious so that 
> people don't miss it, but not so annoying that it makes the document 
> difficult to read (ie. no flashing "obsolete" watermark as a background 
> image).

I was thinking the same.  I like how w3.org handles versions, status,
and related documents.

> >Sections:
> >
> >API
> >	This API content is derived from source packages.
> >	Editions are represented as major.minor releases of the API.
> >  
> >
> Currently the docs are versioned by Gnome platform version (sort of).  I 
> suppose going by package version probably makes better sense (eg. GTK 
> 2.2 docs are applicable to the Gnome 2.2 and 2.4 dev platforms).
> 
> It would be good to have some pages linking to all the documentation for 
> the "Gnome X.Y Development Platform".

I was thinking that the site needs a template to render the DocBook
material with a unified style for the site.

> >Programming guides 
> >	This section includes rules of programing, white papers, 
> >	and some of the existing features.  Some current guides 
> >	appear to be tutorials.  Obsolete guides, such as those that
> >	references old APIs, will be kept as an historical reference.
> >  
> >
> Would versionning these guides according to Gnome platform version make 
> sense?  If a new revision of a guide covers a different Gnome platform 
> version, would you keep the old one?

The value of the library is that it preserves the older material.  Some
developers/companies cannot upgrade their code quickly enough, so we
need to offer the resources they need.  Of course we need to convey to
the developers that the documents are obsolete, and provide some
direction to where the developer can learn the consequences of not
upgrading.

> >Programming tutorials & books
> >	This section contains introductions to the API, tutorials, 
> >	primers, and some archived features belong here.  Obsolete 
> >	tutorials, such as those that references old APIs, will be 
> >	kept as an historical reference.
> >Policies
> >	This section publishes the current policies about accounts
> >	on the GNOME servers.  Older editions are not kept.
> >Development FAQ
> >	Common questions and answers are kept in this section.  
> >	Outdated questions may be moved to the bottom of an FAQ
> >	section, or revised; irrelevant content will not be archived.
> >Standards 
> >	Current and older GNOME standards are published in this section.
> >	Links to other sites like freedesktop, w3c, and omg will direct
> >	developers and business users to the open standards that GNOME
> >	supports.
> >Case studies
> >	The content for this section does not exist.  Case studies are
> >	needed to illustrate the value of GNOME to developers and 
> >	business managers.
> >  
> >
> I think these should really be on www.gnome.org and made quite 
> prominent.  They should be one of the things we use to sell Gnome to people.

I included cases studies in my use cases for w.g.o.  I think case
studies will sit well in a library because they will be used by
developers, users, and, organizations.  Case studies will become dated
so it would be better to depreciate them then toss them away.

> >Contributor interviews
> >	This section lists interviews with GNOME contributors from 
> >	latest to oldest.
> >News
> >	This section lists the GNOME summaries from latest to oldest.
> >	If they grow too many for the page, they will be grouped by
> >	year.
> >Foundation charter and bylaws
> >	GNOME organizational documents are kept in this section.  Older
> >	versions of documents are kept for historical reference.
> >  
> >
> Wouldn't these fit better on foundation.gnome.org?

I think it does.  Putting it in the library is a stretch.

> >Press releases
> >	Press releases are listed from latest to oldest.  If they
> >	grow to be too many for the page, the site may group them by 
> >	year.
> >  
> >
> Is there any particular reason to move these off of www.gnome.org?  I 
> think it would be good to incorporate the year into the URL of press 
> releases too, btw.  It would make it more explicit whether a particular 
> press release is news or not, and reduce the chances of name collisions 
> (eg. from the name, it isn't clear whether 
> www.g.o/press/releases/newcommitments.html is quite old).

Sending the press and users to a URL with library in stead of www as the
host undermines the authority of the press release.  Moving old ones to
a library sounds sensible, but I dislike breaking inbound links.

> >User and administrator guides
> >	This section offers guide for users and administrators, 
> >	organized by GNOME releases.

-- 
__C U R T I S  C.  H O V E Y____________________
sinzui cox net
Guilty of stealing everything I am.