Re: user guide update

[Shaun McCance <shaunm gnome org>]

Big thanks to Joachim, Daniel, and everybody else
who's taken the initiative to Get Stuff Done.

On Sat, 2006-02-11 at 20:14 +0000, Joachim Noreiko wrote:
> Just a quick update of what I'm doing...
> 
> I've just added the section 'Giving Focus to a Window'
> to CVS. Thanks Daniel for your work on this on the
> wiki :)
> 
> More generally, here are my thoughts on the plan for
> 2.14 in the time we have left.
> 
> Being realistic, I don't think we'll have time before
> 2.14 to do big rearrangements of topics. I imagine
> most users enter the guide somewhere in the middle by
> clicking on Help buttons. I would like to add a
> section on switching off somewhere prominent, and I
> think I mentioned moving stuff on sessions or
> workspaces further down, but it's not a priority.
> 
> There's a lot of sections I'm itching to rewrite for
> general clarity, but again I'm not sure that's the
> best use of our time right now. 

Just having the information be correct and complete
will be a huge improvement.  If this level of work
continues to go into the User Guide, then it will
gradually converge towards perfection.

> What we should be able to do is provide 2.14 with a
> user guide that is actually up to date :)
> I now have access to an up-to-date version of GNOME
> (thanks to Brent, yay!!!), so screenshots are a
> definite possibility. It's not a disaster that
> screenshots show an out of date theme, but it's
> something people notice.
> 
> Who out there is interested in working on the user
> guide?
> Some parts are so old that access to 2.12 is enough,
> and the method I'm using to get the current build
> should be available to everyone soon anyway.

I do actually contribute to user documentation,
though it may not be obvious.  In the past few
releases, I've done the primary maintenance on
the Bug Buddy, Configuration Editor, and Sound
Juicer manuals.  I'll do them again this time
around.

And I will gladly help out with the User Guide
as well.  You've got the reins now, so perhaps
you could put together a bullet list of what
should be worked on.  Something like:

* Section "foo" describes Gnome 1.4
* We should add a section "bar"
* Section "fum" was written by a machine

> As far as writing DocBook goes, I'm happy for people
> to submit single sections to me rather than patches:
> that's perhaps easier.
> Just wrap paragraphs in <para> and the whole thing in
> <section>, just like HTML, but not ;)
> IIRC, you can drag an XML file containing no more than
> that straight to the Yelp window and it'll display it.
> 
> And as far as checking your markup goes, the hackers
> on this list will probably kill me for saying this,
> but I find that it Yelp doesn't choke on it then it's
> probably fine :)
> 
> If you'd rather work on the wiki, it's ok to just
> indicate what should be changed from the user guide
> that comes with 2.12.

I have a long-standing offer to mark up people's
text.  If you write good material, I'll turn it
into good DocBook.  Ideally, all our documentation
would go through a series of reviews, with a final
review being done by somebody capable of addressing
markup issues.

--
Shaun