I thought I'd throw together some use cases for ProjectMallard.

Gedit Plugins

Gedit has a plugin architecture. The basic gedit installation comes with a small number of core plugins, whose documentation is contained within the gedit manual. This is all in the gedit CVS module.

A further set of plugins is released as a separate package. Documentation for these, if it existed, would go in this gedit-plugins CVS module.

Yet more plugins are created by third parties. Users drop these into their local settings folders. Documentation for these would presumably be provided by the same third party. To keep installation simple, it might get dropped in the same folder as the plugin.

Inserting special symbols and foreign characters

Users need to know how they can insert symbols not on their keyboard: accented characters, symbols, anything else unicode can provide. Gnome provides several ways of doing this: the CharacterMap, the insert symbol applet (I forget the exact name), and the Compose key (this is actually supplied by X, and it's antique and nasty, but useful nonetheless).

Documentation for this would be:

• In the User Guide, a section called "Inserting special symbols and foreign characters" would provide an overview of the three methods, and link to:
• The Character Map manual. This is within the same module as the app.
• The insert symbol applet manual, which is in whichever micromodule it lives in.
• The Compose Key, which would (probably) be another page in the user guide.

Fortunately, all these things are stock gnome (just checking: is the compose key guaranteed to be present? I'm killing someone if not).

As the user follows the links, the transition should be seamless: currently, jumping to another manual in yelp is quite jarring (things jump around, the contents pane reloads, etc).

(This raises the question: do we still want a contents pane, or do we want a less linear list of related topics?)

EOG and EXIF

EOG, the image viewer, has extra features available if certain libraries are installed. For example, libjpeg allows an image's EXIF data to be seen (bug 382234 for more information).

Here's what would be cool: the topic on showing EXIF data is only visible if this library is installed. The troubleshooting section should have a corresponding "I can't see EXIF data" topic, which might as well always be there.

Distro / admin name -- global entities

A corollary of the above is that it would be good to be able to say "Ubuntu" instead of "your distro", and have a standard link for getting help specific to the distro. This basically calls for global entities that all documentation can use, eg &distro;.

I can also imagine the default text "For more help on this, (contact your distro)." being replaced with any of the following depending on the installation:

• For more help on this, (see the Ubuntu system guide)." (this would be a link)
• For more help on this, (contact your system admin)." (A particular deployment of Gnome could insert the email address of the helpdesk)

Distros change main menu

Sorry to say I don't see how Mallard can address this. See http://bugzilla.gnome.org/show_bug.cgi?id=398134 -- basically, OpenSuse changes the Application menu to something else.

One lateral-thinking solution would be to start assuming the user is intelligent to know how to use the Applications menu (it's documented in the User Guide anyway) and drop the slightly patronizing "How to start" section from all manuals.