No way to browse applications' manuals

[Luca Ferretti]

Binary package hint: yelp

In Yelp (gutsy) I can't find a way to browse all installed manuals. This meas, for example, that users will have to start an application in order to open and read the inline help, as well as accessibilty and system admin guide from gnome-user-docs package are virtually inaccessible (unless finding links in other manuals or manually opening using ghelp:gnome2-accessibility-guide).

A solution to this could be provide a link to original (upstream) Yelp's topic page somewhere, for example under "Advanced Topics" document.

[Maurizio Moriconi (bugman)]

+1 for me

[Sebastien Bacher (seb128)]

Matthew, that's due to the Ubuntu layout patch, could you have a look?

[Matthew East (mdke)]

Thanks for the report. This is an intentional result of our customisations to Yelp, which have been the subject of substantial discussion throughout the last two or three release cycles in the documentation team so for now I'm closing this bug as WONTFIX.

The topics currently available should cover most subjects relevant to the desktop user, and inside each topic it should be possible to browser to relevant manuals (and relevant index pages from upstream). The idea is to enable Ubuntu-created documents and upstream material to be merged into the structure rather than separate. Naturally, all the installed manuals are available from the search function as usual (which is where most users actually start).

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.

[Sebastien Bacher (seb128)]

the manpages are accessible from the advanced topic left column item which is easy enough to use

[Matthew East (mdke)]

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.

[Jan Claeys (janc)]

I think hiding installed documentation is definitely *not* a good idea.

E.g., where have the Python documentation & tutorials gone?
I thought Ubuntu wanted to promote python programming/scripting?

[Sebastien Bacher (seb128)]

you want to use devhelp not yelp for programming documentation

[Matthew East (mdke)]

On 07/10/2007, Jan Claeys <email address hidden> wrote:
> I think hiding installed documentation is definitely *not* a good idea.

You're entitled to your opinion, but we've discussed this in detail
over several release cycles with plenty of research.

Have a read of https://wiki.ubuntu.com/HelpfulHelp which is probably
the best analysis of the help system.

Two of the key points are:

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

> E.g., where have the Python documentation & tutorials gone?
> I thought Ubuntu wanted to promote python programming/scripting?

Funnily enough that's one of the categories which is still present:
Advanced Topics -> Writing your own programs.

Those links are broken in the current yelp, although that's another story / bug.

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

[Luca Ferretti (elle.uca)]

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

[Matthew East (mdke)]

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