Comment 10 for bug 147668

> 1. Blindly listing documents by application name without a coherent
> categorisation means that regular users are just going to stop reading
> the help and go somewhere else.

Matthew, please note that the "Advanced Topics" document starts with this phrase: "The Ubuntu help system contains a lot of documentation, not all of which you see in the table of contents". You can, of course, use the search feature, but as well as you allow to browse man and info pages by category (Advance Topics->Terminal Commands References // Advanced Topics->GNU Info Pages), I think we should allow to browse XML/Docbook manuals by category too.

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.

So, IMHO, hiding the index for XML/Docbook documents is a bad idea: it should be available near the man in info index. You can of course use a different default approach to help users to browse, but any documentation system needs an index.

> 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. Could be solved in deb package build, splitting doc stuff. However, note also that XSTL manual is listed under "Other documents" category, the proper category for "other" stuff: if you are browsing here, you should know that you can find odd stuff :-)

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

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

> If there are specific pages which you believe should be included in the current setup, and aren't, please file
> a bug on ubuntu-docs.

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.