On Dec 18, 2006, at 11:36 PM, Joachim Noreiko wrote: > > --- Matthew Paul Thomas <[EMAIL PROTECTED]> wrote: >> >> Do you think possibly those two things are related? ;-) Depth-first >> traversals of the user interface are not an exciting thing to write, >> or to read. And writing the eleventy-twoth version of "When you start >> &app;, the following window is displayed" can't be fun, either. >> Meanwhile, for example, Totem has no "What to do if a movie won't >> play" help page, Rhythmbox has no obvious "Sharing your music" help >> page, and Seahorse has no "What are keys used for?" help page -- all >> of which would be more interesting to write *and* more useful to >> read. > > 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. :-) > Identifying those topics you suggest takes time, it's harder to know > when you've covered the matter at hand comprehensively, and it's also > a lot harder to provide useful information. Eg, I don't have a clue > what to do if Totem won't play a movie (in my personal experience, it > gives me a cryptic message I don't understand, so my solution is 'make > a note of the URL and go boot your mac') 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> > ... > I would very much appreciate your input on exactly the sort of thing > you've suggested above. More generally, structure, style, and tone of > documentation. Well, I realize I have zero karma here because my contributions to upstream Gnome documentation are non-existent :-), but these may be helpful. (Sorry for the Ubuntu focus, but they apply pretty much to all Gnome-using OSes.) * 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> > For example, Shaun's asked me to think about how a manual might be > structured with Mallard. I've started with gedit here, and I've very > much appreciate input: > > http://live.gnome.org/ProjectMallard/StructureTestCase That looks pretty good, except for the "(plugged in from the User Guide)" parts. For example, if the "Undo and redo" page was plugged in from the User Guide, it would no longer be able to tell you where to find the option in GEdit's Preferences for the number of possible undos, which the help currently does. > I've also thrown together a few random thoughts here: > http://live.gnome.org/ProjectMallard/DocumentationStyle Good thoughts. Basically, "omit needless words". :-) >> Good on-screen help has "Show Me" buttons. > > I was just thinking about that. Does Yelp currently support anything > like that -- a button that says "Open Thingy Preferences" for example? > ... I'm pretty sure it doesn't. Actually, I don't think it's possible for *anything* to Open Thingy Preferences at the moment, unless Thingy happens to have a command-line option for it. :-( How could we fix that? Perhaps: (1) the Mallard-powered help viewer gains the ability to tell applications to run scripts (2) one brilliant app developer is talked into making his/her app's GUI fully scriptable (3) the app is rewarded with wonderfully interactive help pages (4) an example is set, and other app authors start doing the same. -- Matthew Paul Thomas http://mpt.net.nz/ _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
