Comment 11 for bug 147668

Hi,

On 16/10/2007, Luca Ferretti <email address hidden> wrote:
> Just a real case example: the Italian GNOME team provides guidelines for
> Italian translation. I wrote those using XML/Docbook, packed inside a
> tgz that works like the gnome-user-docs source package: run
> configure/make/make install and read in Yelp. It's an external and
> additional document, of course, and it's useful only for Italian
> translators: there is no interest to merge it in the structure of Ubuntu
> documentation system. This to explain that the GNOME help system can be
> used to provide more then application manual.

That's fine, and is no doubt a good resource, but it's not relevant to
Ubuntu desktop users (which is what we use yelp for). There are any
number of ways that you can allow people to view that, such as
providing a copy of the document on the internet, html files viewed on
a local system, or even docbook xml viewable by calling yelp from the
command line, if you really want to use docbook as your final format.

But it certainly shouldn't be part of the help system, for the reasons
I've given.

> > 2. Quite a lot of the documents listed in the standard yelp indexes
> > are totally irrelevant to the vast majority of desktop users and
> > confuse them rather than assist them (e.g. "GNOME Documentation XSLT
> > Manual").
>
> This is a different issue, not related to provide an index for
> XML/Docbook.

I don't see how: I understood your original argument to be for all the
upstream categories to be included. Now you appear to be arguing for
us to include just one link in the help structure to a complete list
of all documents which have an omf file installed on the system,
unless I've misunderstood. I still disagree with that, and I think the
arguments in my previous comment still apply.

> > And just to note that both the major Gnome manuals (accessibility
> guide and user guide) are incorporated > into the layout. The
> Accessibility guide now has its own entry.
>
> system-admin-guide guide seems still out to me.

Yes, it doesn't contain much useful material for our purposes.

> As well as manuals from the new gnome-devel-docs module. maybe this is
> not yet included in Ubuntu, but it provide useful sfuff: an overview of
> GNOME Desktop for developers, the HIG, the style guide for manuals and a
> simple guide to integrate non-GNOME apps in GNOME Desktop (application
> menu, mime type, icons...)

Currently we have a section for development material - the programming
article - important documents might be included in that. For myself, I
think that including developer documents is not part of the function
of a desktop help system, and is harmful to the experience of ordinary
users. Information on Ubuntu development is found in a single place at
the moment - https://wiki.ubuntu.com/UbuntuDevelopment and I think
that's appropriate.

> I could like something like the attached HTML for Advance Topics page
> (note the All Installed Manuals section, come from my previous
> considerations); links should open related pages on standard gutsy
> system, except stuff from gnome-devel-docs (platform-overview and hig-
> book).
>
> But it's too late for gutsy, so I'll propose it in the next 6 months.

Right, I'm not convinced yet but feel free to raise it on the mailing
list if you want.

--
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF