RFC: TopicBasedHelp specification (sec=unclassified)

Stoffers, Robert LAC Robert.Stoffers at defence.gov.au
Mon Nov 13 03:23:47 UTC 2006

- snip -
> 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
- snip -

However this is reinventing the wheel, all of these things exist today.
Don't like Docbook? There exists already many different XML formats that
may meet your needs, Guide XML[1] comes to mind for example. Are you
creating your own XML schema or something totally new?

> 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.

I see this as a new way to quickly help a user on the spot with just the
facts (bit like frequently asked questions on IRC or forums). I don't
see this as a way to replace traditional, in depth documentation that
people can actually learn things from. The usefulness of such as system
is diminished to the level of traditional documentation if the user has
to open up a viewer to access it and navigate to the right topic anyway.

> 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
> > 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.
- snip- 

> 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).

That's great but it doesn't address my original concern that some people
have the attitude that "everyone should do whatever Ubuntu/GNOME are
doing" regardless of how others feel about it (even if they like the
idea, shoving it down peoples throats as "the only way" isn't likely to
gain you much support).

- snip -
> > > Do we really gain a vast improvment over what we currently have?
- snip -

> And how many people use the Yelp / KHelpCentre currently?  

I would say the majority of users seeking help read on-line
documentation (whether it be our own or that done by a third party)
rather then what is supplied by Yelp/Khelpcenter. Based on my personal
experience this is what I and people I know/work with do. Most people
have learnt to skip over any local documentation systems thanks largely
in part to Windows local help being so dismal for so long. 

The above doesn't mean we should change how we document things however,
I feel that we simply need a better system then what Yelp/Khelpcenter
currently provide us with (preferably a much simpler one too). Topic
based help will only be truly useful if it is embedded directly in each
and every application and displays results based on the current context
of the application in question. Replacing traditional documentation with
topic based help simply puts us in the same situation as we are now with
a help system that no body wants to use (and yes, the Windows help
system is now topic-based and still no body uses it, from my

> 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
> (Not Ubuntu / GNOME / KDE obviously, the Other One).
> 2) They are looking for something in particular to answer a question.

I wonder how many of these people turn to Google or friends that
introduced them to Ubuntu rather then Yelp? I suspect it would be most.

> 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.

I would like to see:

- A dynamically created (by some local system) web page detailing a
welcome to GNOME/distribution introduction and links to both local and
on line documentation and support options.
- An icon on replacing the Yelp help icon in the menu that opens this
page in a web browser (Firefox, Epiphany).
- The Yelp viewer dropped in favor of just using the default system
browser to view both on and off line docs.
- No monolithic lists of application specific documentation. Have the
help accessible either via an embedded means directly within the
application or accessible via a link in the application that opens up in
a web browser.

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

If this is imbedded directly within applications with links to
appropriate sections within traditional documentation I agree. I don't
agree with a system that simply exists to replace traditional
documentation, unless it is embedded and relevant to the current context
of the application then the user still needs to open it, navigate it and
still needs to know what he/she is trying to achieve. Topic based help
is therefore no more useful to such a person then what traditional
documentation is.

- snip -
> > 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. 
- snip -

Well you can:

- Create your own XML schema
- Look for an existing one (such as Guide XML) and use that
- Reinvent the wheel, put everyone on another learning curve, spend much
time implementing it

> 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].

- You want each application to update its own little part within a
larger system? Isn't this kind of what Yelp already does today? 
- How can this be controlled to not end up looking like the useless
monolithic lists of application specific documentation in Yelp already? 
- Won't this become even worse when under each application there might
be 50+, 100+ or even 1000+ different "topics"?
- Won't this just mirror both the table of contents (in layout) and much
of the content of traditional documentation anyway (just under "topics"
rather then headings/subheadings)?


Robert Stoffers

[1] http://www.gentoo.org/doc/en/xml-guide.xml -  A very nice XML markup
schema created by Gentoo for its documentation. Much simpler then
Docbook. Example:

<title>This is my chapter</title>
<title>This is section one of my chapter</title>

This is the actual text content of my section.


Looks a lot like HTML and is thus easy to learn for anyone who has ever
dabbled with HTML. 

More information about the ubuntu-doc mailing list