Shared documentation system

[Shaun McCance]

On Mon, 2003-12-08 at 05:27, Thomas Leonard wrote:
> On Sun, Dec 07, 2003 at 09:37:35PM -0600, Shaun McCance wrote:
> > On Sun, 2003-12-07 at 20:44, Murphy wrote:
> > > And, after all, we can't forget whatever GnuStep, etc
> > > help systems there are or may be in future.
> > 
> > Sorry, I meant to say something about this as well.  I'll admit I have
> > absolutely no idea what desktops other than GNOME and KDE are doing for
> > documentation, and I only have a vague idea of what KDE does.  People
> > from Rox, XFCE, GNUstep, and any other desktops should certainly throw
> > their thoughts in.
> 
> Well, since you asked (though I don't suppose it's very useful):
> 
> We store application documentation inside the applications, so we don't
> need an indexing system (the same GUI object that runs the application
> when clicked also offers a menu with Help on it). So, application help is
> always with the application it describes, and the same mechanism is used
> for organising both.
> 
> The Help menu item opens the directory containing the help files inside
> the application (so you don't need to run any of the app's code to read
> the help). All normal document formats are therefore supported. Plain text
> and DocBook/HTML are the normal ones, and the normal file association
> mechanisms are therefore used to set which programs to open them with.
> 
> Help that isn't attached to any application (HOWTOs, etc) just have their
> own directory anyway, so you can put them in /Documentation/HOWTOs, etc
> and access/search them via the normal filer interface, as with your other
> documents.

All right, I figured it was something like that.  That similar to how
MacOS X does things, which is to be expected.

> What's wrong with using a web browser? It was stated in the first post
> that 3rd parties tended to do this (with the implication that it was bad).
> Users already understand their web browser, it can read lots of formats
> (including DocBook and other XML formats using an XSLT stylesheet), it
> works on the console or in a GUI, etc.

As far as I'm concerned, the only thing that a help viewer and a web
browser have in common is a document viewing component.  We have many
good reasons for having a dedicated help viewer in GNOME.  Regardless,
I'm not here to argue what sort of application each desktop should be
using to view documentation.  That's a policy decision, and one of my
stated goals is that the help system should impose very little policy.

--
Shaun