Comments on Help System Spec and Spoon

[karderio <karderio gmail com>]

Hi :o)

I read the Help System Spec and checked out Spoon last night - I must
say this all seems most excellent ! Can't wait : great ideas, and if the
implementation finally resembles all that is suggested on the wiki, you
may just have built the world's best software help system !

One idea - when it says "Documents should have a simple and consistent
way of referencing other pieces of documentation, independent of the
desktop environment." could this not be independent of the presence of
said document on the system also - say provide a web address in case the
doc is missing for example ? Thus, in a doc we can reference other
documentation, regardless of it's presence or not, or conversely, we can
reference a doc on the web, but use the local copy if one exists. I'm
not sure how this could be implemented, perhaps you would need a web
service that could be called with a docs id, if a doc is missing.

What type of documentation is covered by the doc system ? Maybe a
specific domain should be given in the introduction. Can the doc system
be used to document domestic appliances, or is if for software only ? Is
it for GUI software only, or can it be for the command line also ?

Could the build system have an option to provide a manpage if a project
is missing one ? It could be a simple explanation of where to find the
actual documentation for example, or even the complete documentation
itself. Some distributions insist on a manpage for inclusion, and some
people are used to typing "man [command]". Also this would ease
accessing the documentation from the command line. Perhaps this
documentation system could supersede man pages and info pages, by
providing a nice terminal based interface. If this interface supported
both "mallard", info and man, it could replace the man and info
commands, and add a new command "help". I realise this is out of the
specs scope, I'm just getting carried away with the possibilities of
this thing !

I'm worried that the fact that meta data being stored in a specific
place could pose permission problems. What if we don't have permission
to put our scroll in that directory ? Currently, AFAICS, if I install a
GNOME app, I must install it's help in a specific directory for the app
to be able to display it. Perhaps I'm missing something, but it seems
that if you do not have root privileges, an app *can't display it's
help*. I have a piece of software where I recommend to users to install
it in their ~/.local directory, but have to explain to them how to place
symlinks so the docs will work... I hope I'm wrong about all this ;)

When invoking the help browser, the spec says "Both methods are
asynchronous and are not expected to return anything." I would argue
that these methods should at least return weather the help has been
properly displayed or not, in order that we may show an error message to
the user if the help wasn't found or some other problem. I think this is
important, even in the best of current systems a file can get deleted or
become corrupt. There was a blog entry dicussing a similar theme
recently on planet GNOME [1], I rather agree with the author. Comment
[2] contains a practical example of actual code, for which not having a
return value would cause problems, if you like.

Apart from that, I find everything just fabulous ! One phantasmagorical
idea that came to mind while writing this would be some sort of
Document-O-Sphere - a central place one could come to when looking for
documentation, as if one were consulting the Wikipedia, with a universal
unique way of identifying documentation. This would of course concern
other things than software documentation. It would permit things like
just printing the document identifier on say, your new computer
keyboard : you would go to the Document-O-Sphere with this identifier
end get the docs, which are shown in your default documentation browser,
saving on paper/disks and guaranteeing up-to date documentation. Such a
thing could be based on a centralised, distributed or peer to peer
model. I'd be happy to throw ideas in a pile if anybody thinks the
concept is worth exploring.

Keep up your most exquisite, wonderful work !

Love, Karderio.




[1] http://blogs.gnome.org/view/timj/2006/11/24/0

[2] This is how I display help in a project I'm currently working on,
the errorDialog function displays a gtk dialog for the user and prints
the error message to the appropriate standard output :

void help(gchar* section)
{
	GError *error;
	error = NULL;

        gnome_help_display_desktop(NULL, "glipper", "glipper", 
                                   section, &error);

	if (error)
		// do not translate this string until we sort out translations
		errorDialog(_("Could not display help for Glipper"), "Is the help
properly installed ?\nSee the notes section of README file for a
possible solution.");
		g_error_free (error);
	}
}