Re: Gnome User Guide

[Shaun McCance <shaunm gnome org>]

On Thu, 2005-12-08 at 23:07 +0000, Joachim Noreiko wrote:
> --- Shaun McCance <shaunm gnome org> wrote:
> > The User Guide is horribly out of date.  And without
> > an
> > active community of good technical writers, I can't
> > make
> > any guarantees as to when it will cease to suck.
> 
> I've checked out the CVS and I've started to wade into
> the User Guide files.
> Are there any particularly sucky bits I should focus
> on first?
> 
> Are there any technical changes I should also make?
> Eg, I see a lot of comments <!-- Maintained for 2.8
> compatibility -->. Are these to be kept or cleaned up?

Basically, the ID attributes did this numbering thing.
Any utility numbered IDs have is completely negated
once you move sections around.  And you *will* move
sections around, no matter how perfect you think your
first version is.

So I started using more semantic IDs.  The problem is
that Help buttons in Nautilus and such will request
a particular section by ID.  We should absolutely
change all of those to use the better IDs, but we
still need to maintain the old IDs, at least for a
while, for other applications.  So any ID that once
existed should be put into an anchor tag somewhere
in the document.  Even if a section is removed, an
anchor for that section should be placed at the most
relevant alternative.

--
Shaun