RFC: TopicBasedHelp specification

[Don Scorgie]

Guess that's my cue to step in ;)

First, a buzzword description of Mallard for those that aren't familiar
with it:

Project Mallard isn't just about topic-based help.  Project Mallard is
the culmination of years of experience in building help systems.  It is
a combination of several key new technologies.  The centrepiece will
indeed be a topic-based help system.  In addition to this there will be
a new markup language, a new metadata system, a new editor for writing
and translation documentation and various other interesting projects.
The new topic-based help will allow a better synergy between GNOME
upstream and distributions downstream.  It will allow segments of
documents to be altered and integrated with easy, without the current
licensing problems, to suit distro's default layouts much better, where
they differ from GNOME defaults.

There, how'd I do?  Enough buzzwords in there?  I'm sure I could squeeze
a few more in if desired ;)

On Mon, 2006-11-13 at 08:30 +1000, Stoffers, Robert LAC wrote:
> I've been silently following along with this thread (as I tend to do
> with the Ubuntu-doc list) but one thing strikes me as plainly ignorant:
> 
> > Then please do whatever you can to get KDE using a topic-based help
> system sometime in the next six
> > months as well. It's a better approach regardless of the environment
> you're using.
> 
> This isn't the first time I have seen someone from the Ubuntu project
> simply dismiss what KDE (and by extension Kubuntu) are doing and suggest
> that they follow along with whatever GNOME/Ubuntu are doing because it
> is more convenient for Ubuntu. This is the wrong attitude to take, don't
> be surprised if the response is something along the lines of "rack off"
> (as some of you have found in the past). 

KDE also have a topic-based help system under construction [1].  It's
been in the works about as long as the GNOME one has (which is quite a
long time, long before Project Mallard was granted its name).  If
anything, they're more advanced than the GNOME version, despite my (and
others) best efforts.  I believe the KDE version is more having some
small tutorial-like docbook docs (though, I don't really know).

<avoids comment that GNOME gets its fair share of "You should do this
because KDE do it>

> 
> I've read over what little there is in the way of documentation
> regarding Project Mallard and I'm personally yet to be convinced that it
> is the ultimate solution to everything. The only thing this project is
> achieving right now is stagnating work on any other improvements that
> could be made to the GNOME/Ubuntu documentation process while everyone
> sits and waits for the project to do something.
> 
> > > Do we really gain a vast improvment over what we currently have?
> 
> >Yes.
> 
> Such as what? Seems like a whole lot of work only to end up with even
> less useful content. Nobody I know uses Windows in-built help system
> regardless of the improvements they make to it, why go down this path
> too?

And how many people use the Yelp / KHelpCentre currently?  Comparing
upstream bugs for yelp and the GNOME docs against any other products.
We get far, far fewer than pretty much anything else [1.5].  Now, much
as I would like to say that's due to sheer programming / writing
brilliance on our part ...

People generally use computer help for 2 reasons:
1) They are new to computers.  They want to learn how things work.  They
haven't already sussed that computer help is (generally) pretty terrible
(Not Ubuntu / GNOME / KDE obviously, the Other One).
2) They are looking for something in particular to answer a question.

There is nothing stopping (1) being done in Mallard.  There would be a
generic "Welcome to GNOME" type document that would do exactly that.
With Ubuntu customisations, this guide could then be altered to fit more
into the default Ubuntu setup by (e.g.) replacing the web browser
(upstream: Epiphany) section with the Ubuntu version (Firefox).  This
currently can't be done due to licensing conflicts.  Win there.

In (2), this system is just better [2].  Win there.

> 
> > Having each topic in its own file will make it easier for multiple
> licenses to coexist.
> 
> We can do this using Docbook right now, what difference/benefit will
> reinventing the wheel aka Project Mallard give us in this respect?

Docbook sucks.  Its designed to be an all-in-one language for writing
absolutely anything.  It has hundreds of elements in it.  Doc writers
are confused by what each element is used for and where they are
appropriate.  Writing stylesheets that look good for docbook is tough
because of the number of elements and the fact that different people use
different elements to represent the same thing.  Parsing docbook
correctly takes a long time (due to the number of elements).

In addition, to put each section into a docbook file, you must
<xinclude> the file (or equivalent) in the main document.  If it isn't
found, things break.  With Mallard, the section will be used if it's
found by the metadata system.  If another version of the section is
written and registered correctly later, it will be used instead.  This
is not only a benefit in that separate sections can be distributed
independently (hence, better updates), but also (as an example) when
xchat is installed and xchat-gnome is removed, the user guide will
automagically update to show a section on using xchat instead of
xchat-gnome [3].

Hope this helps a little
Don

Here come the disclaimers:
[1] Which obviously I can't find a reference to now.  Grr.
[1.5] Even with the recent bug-buddy work, we still get very few bugs
compared to other GNOME apps.
[2] See the first 2 sections of
http://www.gnome.org/~shaunm/quack/mallard.xml
[3] In an ideal world