Re: Yelp

[Shaun McCance <shaunm gnome org>]

On Tue, 2004-02-03 at 09:10, Eugene O'Connor wrote:
> Shaun McCance wrote:
> 
> [snip]
> 
> > > A number of issues mentioned where the docs guys think Yelp could use
> > > some work are:
> > >
> > > - index keyword search: I know Scrollkeeper inside out so I know that it
> > > supports index search if index markup is provided in the docs and I also
> > > know that Yelp has support for this, but the 2.4.0 version I am using
> > > does not display any index present in the docs
> > >
> > > - search in documents: this is not supported at all, some kind of text
> > > indexing facility that indexes all docs and provides search though Yelp
> > > would be great
> > 
> > Searching is the killer feature that we're all waiting for.  There's a
> > lot of work that needs to be done to make it work well, and I've only
> > just begun working on it.
> 
> I think displaying index terms is as important as searching. As a user,
> this is always the first place I look. If I cannot find what I want in
> the index, I use the search. Does Calum have any insight to how users
> use these features?

Yes, agreed.

> > > - UI: it has been mentioned that the UI could use a facelift, it is not
> > > very obvious for me what this means, but we could work on identifying
> > > issues if it comes to it
> > 
> > I want to move away from a browser interface.  Currently, we have Back,
> > Forward, Previous, and Next.  This sort of thing happens all the time in
> > browsers like this, and it really confuses people.  I'd like to rethink
> > the Back/Forward thing and focus more on Yelp as a structured viewer for
> > structured documents, rather than a document browser.
> 
> Can you provide more information on the difference between "structured
> viewer" and "document browser". I'm not 100% sure what you mean. Are you
> saying that users get confused by the difference between "Back/Forward"
> and "Previous/Next"?

Without any actual studies to back me up, I am definitely saying that. 
I've gotten confused by it before on other help applications.  Notably,
the Civilization 3 "Civilopedia" still manages to confuse me from time
to time with its structure.

Part of the problem is that the user isn't always thinking in terms of
the logical book structure.  Often the user is just looking at some help
page, without thinking of it in terms of a book.  Pat just sent an email
talking about differences between manuals and quick help pages, which I
think was spot-on.

> The Sun GNOME doc team suggested that Yelp needed some look-and-feel
> improvements in our GUADEC 2003 presentation (see
> http://developer.gnome.org/projects/gdp/articles/guadec-2003/GUADEC4_whitepaper.html).
> In particular we suggested that the stylesheet could be improved (see
> screenshots in the Future, Technical Aspects section).
> 
> We also suggested that the general appearance of the Yelp front-end
> could be more visually appealing. 

Yup, I've read that, and I generally agree.  I have tried to make the
output of Yelp's stylesheets nicer, and I think I've had some success. 
I think the rendering in KDE is overkill with the big banner at the top
of every page, but there is still a lot of room for improvement in Yelp.

One thing we have to keep in mind is accessibility.  Without some sort
of themeable stock color set in GTK+ (which we don't have), there's only
so much I can do in terms of using colors for visual offset.  I'm also
very limited by not being able to change fonts.

This leaves me with margins, font sizes, bolding, and italics.  Italics
can't be relied upon too much, since there's no concept of italics in
non-Latin writing systems.  These are basically all the tools available
to print typographers (except they can do screening too).  But many of
the techniques that work well in print don't work as well on screen,
especially since we have ragged right edges.

[snip]

> > > I know that the Shared Documentation System thread on freedesktop.org is
> > > about making everybody's life simpler by getting rid of middlewares like
> > > Scrollkeeper. Scrollkeeper provides some functionality that people will
> > > need as build tools if Scrollkeeper is not present (like index and TOC
> > > extraction from docs). It would be good to know how and when you plan to
> > > move away from Scrollkeeper.
> > 
> > I don't know when.  I've been trying to write up a draft proposal, but I
> > keep getting sidetracked trying to fix Yelp bugs.  Hopefully I'll get a
> > chance to work on it and post it later this week.  Then it's a matter of
> > having discussions and hammering things out.  There's really no telling
> > how long that will take.  I'd love to have it in place for 2.8.
> 
> Will removing ScrollKeeper make it easier to improve the look-and-feel
> of Yelp - the parts of Yelp that I find least attractive are the Home
> page and the categories or documents page directly below the Home page.
> Basically any page that doesn't display a document.

Yes, agreed.  We really need to do some hard thinking about how the
listing of documents is presented to the user.

One of my main beefs with ScrollKeeper is how the category heirarchy is
hard-coded into the category codes.  This is really unflexible.  Using
something else won't make it any easier to present the document listing
differently, but it will help us make a better document listing.