Re: About GNOME / return / duck related question

[Joachim Noreiko <jnoreiko yahoo com>]

--- Matthew Paul Thomas <mpt myrealbox com> wrote:
> On Dec 18, 2006, at 11:36 PM, Joachim Noreiko wrote:
> > Long slogs through the interface are dull to write
> and read -- yet 
> > they are also the easy option.
> There ain't no such thing as a free lunch. :-)

Yup.
But with so few people on the GDP, we're stuck on
picnic nibbles :(

> Perhaps this is another reason for individual
> modules to have help 
> writers closely associated with that module -- so
> that they can be more 
> familiar with tricks and troubleshooting for the
> application, and write 
> more useful help, instead of the application
> developers throwing their 
> code over the wall to the GDP and saying "here,
> document this".
>
<http://mail-archive.com/gnome-doc-list gnome org/msg01868.html>

Throwing over the wall... that's a good way of putting
it ;)

This cycle I've been working quite closely with the
Gedit team to see how we can change the way this
works.
For example, the gedit developers are filing
documentation bugs each time they commit changes to
the interface. This means I can either update the
manual in sync with them, or leave the bugs to form a
to-do list later on in the cycle.
(More on this here:
http://live.gnome.org/DocumentationProjectPolicies)

Unfortunately, there's only one of me, and I can't do
that for every single Gnome app.
(I'm not even sure which are the documents the GDP has
control of. I made an attempt at pinning this list
down, but the result was that I landed myself more
work... *sigh*
You can see the partial list here:
http://live.gnome.org/DocumentationProject/Documents

> Well, I realize I have zero karma here because my
> contributions to 
> upstream Gnome documentation are non-existent :-),

Karma schmarma :)
 
> *   A general review of, and roadmap for, help in
> Ubuntu.
>      <https://wiki.ubuntu.com/HelpfulHelp>
> 
> *   Nearly all Gnome installations are the major
> part of an OS
>      installation, so Gnome help should be cohesive
> OS help, with
>      distributors filling in OS-specific parts.
>      <http://urlx.org/lists.ubuntu.com/d630a>
> 
> *   Death to the FAQ!
>      <http://urlx.org/lists.ubuntu.com/780bb>
> 
> *   Recommended format for individual help pages.
>     
> <https://wiki.ubuntu.com/UbuntuHelp/PageStructure>

Very interesting, thank you. I may poach parts of it
:)
I note one of those pages describes Mallard as
vaporware... ouch... but justified, sadly.

So what's possible while we wait for Mallard, I
wonder?

1. Gnome help should be cohesive OS help

Yes, absolutely.
>From a technical point of view, that's something we
could do now. The Gnome Desktop Guide comes in about a
dozen XML files. We could easily add a heap of extra
sections in a few more files.
These would be all the topics we can't actually write
such as installing new packages etc.[1]
On our CVS, these would just say "Your lameass distro
hasn't written the help for this topic. Kick
them!".[2]
And the Ubuntu Docs Team simply replace this file
wholesale with one they've made themselves.

I know that the Ubuntu docs team tried to embed the
Gnome Desktop Guide inside the Ubuntu Desktop Guide
for Edgy (same idea, but the other way round).
But this failed because of licence issues: the Gnome
DG is GFDL, and the Ubuntu DG is something else.

One idea behind Mallard was that as each topic would
be a separate document, this wouldn't matter.

But here and now, it does matter.
Can anything be done about it?

2. Rewriting our manuals to be more task-oriented.

I think once again, the Gedit manual is going to be my
guinea-pig.
The new structure on the wiki is meant to be used with
Mallard, using its funky plugability to include
sections depending on what the user has installed.
But I can start rewriting the manual to fit the
general model of being task-orientated rather than a
long walk through the interface.

3. Buttons in Yelp that open stuff for you

I'll file a bug :)


[1] Pet gripe of mine. Documentation would be
infinitely easier if there was only one distro. And
slashdotters harp on about how good it is that there's
infinite choice in the free software world... *sigh*
[2] Yeah. I'll probably actually write that.






	
	
		
___________________________________________________________ 
All new Yahoo! Mail "The new Interface is stunning in its simplicity and ease of use." - PC Magazine 
http://uk.docs.yahoo.com/nowyoucan.html