Re: About GNOME / return / duck related question

[Matthew Paul Thomas <mpt myrealbox com>]

On Dec 18, 2006, at 11:36 PM, Joachim Noreiko wrote:
> --- Matthew Paul Thomas <mpt myrealbox com> 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/gnome-doc-list gnome org/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/