--- Matthew Paul Thomas <[EMAIL PROTECTED]> 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/[email protected]/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 _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
