Upcoming UI changes for UNR: Customizing Yelp's Home Page

[Shaun McCance]

On Thu, 2009-09-17 at 13:00 -0400, Kyle Nitzsche wrote:
> Shaun McCance wrote:
> > On Wed, 2009-09-16 at 11:44 -0400, Kyle Nitzsche wrote:
> >   
> >> Just pointing out that coupling the content with the (yelp) viewer 
> >> imposes real restrictions. For example, how can karmic UNR fork yelp to 
> >> point to UNR Help Center when that same yelp is used in karmic to point 
> >> (hard coded) to Ubuntu Help Center (unless changes are made to read the 
> >> target from gconf or somewhere).
> >>     
> >
> > So it could be that the differences in what help you want displayed
> > can be handled by installing (or not) optional sets of pages that
> > plug into the desktop help.  I don't know the scope, so I can't
> > really say for sure.
> >   
> The main home page might be customizable without modifying the yelp 
> package. For example, the top level header for UNR should probably read 
> "UNR Help Center" instead of Ubuntu Help Center". Currently that home 
> page content comes from two file *owned* by the yelp package: toc.xml 
> file and toc2html.xslt file. Note that toc2html.xslt actually provides 
> some of the content (not just styling/formatting) (for example the links 
> under the "Common Questions" header). Thus, currently, to modify the 
> home page help content, you have to modify the help viewer, yelp.

So first of all, note that the default front page for Yelp
in 3.0 will be the desktop help ("User Guide", though I'm
trying to get away from that term).

So, going forward, questions of how to customize the front
page are questions of either how to point to a different
default document or how to customize a Mallard document.

The way we envision things is that Gnome would provide the
desktop help, and distros would then plug whatever content
they want into it.  This nicely handles the case of added
functionality.  What it doesn't solve is modifications,
and that's something we're going to have to discuss.

> > But otherwise, you're asking for Yelp to display a different document
> > by default when launched without a URI.  That really is not a big deal.
> > If you guys want that to be in a GConf key or something so you can make
> > the customization without patching code, we can do that.  I'm here to
> > help.  You just have to let me know.
> >
> >   
> Shaun, that would be totally awesome! It would enable many good things, 
> such as:
>  * the doc team can create a unr docs package that also includes the 
> gconf key that tells yelp to use it. Thus, the help system is switched 
> to point at unr help without having to modify yelp itself.
>  * the current toc page (the home page) in ubuntu docs (the one that 
> shows "Ubuntu Help Center" at the top and that consists of toc.xml & 
> toc2html.xslt) can be moved from the yelp package into the ubuntu docs 
> package, thus making changes to them much easier (the same change would 
> naturally be done to unr docs). Of course ubuntu docs would also have to 
> set the gconf key saying where to point for the homepage. I guess this 
> would also make the diff between ubuntu yelp and gnome yelp smaller too.
> 
> A couple follow on points:
>  * the Help Topics button and the Go > Help Topics menu item also take 
> the user to the home page (through yelp-window.c > window_go_home_cb 
> (...) function). these would also need to pick up the gconf home page.
>  * should there also be a key to point to the xslt that transforms the 
> page (if it is xml)?  As noted above, currently some of the topic is 
> provided by the toc2html.xslt that is provided by the yelp package, thus 
> if that xslt were used, some of the content (and all of the layout) of 
> the toc would not be separated from the yelp package.

I suppose that could be done.  You guys have bolted a lot of
solutions onto the current Yelp setup.  I'd like to see how
many of these problems still exist in a Mallard world before
jumping to these kinds of measures.

>  * Could the pointed to home page be any supported format? (docbook, 
> mallard, x/html)?

Sure.  In 3.0, the default will be a Mallard document.

> >> Given the increasing numbers of distros/images/flavors that consume help 
> >> content, I think it makes sense to consider a model like this:
> >>  * single-sourced content that supports inclusion methods (like xinclude 
> >> and Mallard)
> >>     
> >
> > So Mallard is designed with the idea that you can plug pages into
> > documents.  This is not quite the same thing as pulling pages out
> > of documents to plug them in elsewhere.  So this isn't something
> > you're going to get for free just yet.
> >
> >   
> Not quite sure of the distinction (because I am new to Mallard...).

So a Mallard document is composed of pages, all interlinked
together in various interesting ways.  When I'm writing the
document "Beanstalk Help", I write it with the assumption
that any number of new pages may be added by anybody.

But when I'm writing the page "Planting Beans", I'm writing
it specifically for "Beanstalk Help".  Now certainly, the
fact that we have discrete pages means that remixing is at
least feasible.  But pages are going to reference other
pages, and so they have to assume that those pages exist.

DITA, on the other hand, probably lends itself better to
remixing, because the maps are static.  But that comes at
the expense of losing Mallard's pluggability.

(Note that even with static maps, you're still going to
have to be careful about inline links, which still make
assumptions about what other pages exist.)

> I think, somewhat abstractly, of a sea of atomized content chunks that 
> are pulled into various wrapper documents as needed. This might enable 
> different entry points into a doc system to meet different user needs 
> and experiences, in which the doc system re-uses content for all the 
> good reasons :-), Imagine, for example, that  a software dialog has a  
> "?" mark on it that when clicked launches the help viewer to display 
> just the doc that describes the widgets on the page. (The "UI reference 
> doc" for it). Now imaging a more standard user manual type docs that 
> explain major tasks - it would not need to doc the UI anymore but could 
> include links to that single source content. Then image a trouble 
> shooting guide that would be able to leverage the same UI reference 
> content yet again. This may sound like the talk of a raving dreamer ;) 
> But, I raise these points to highlight aspects of the current framework 
> that make such implementation difficult to achieve as points for 
> consideration by the community.

So I tend to think of a Mallard document as all the help
you want to provide for something.  So let's say you want
to provide user-oriented topics (user tasks, UI references,
troubleshooting pages, etc.)  And maybe you also want to
provide a set of guided tutorials.

There's no real reason these can't just all be pages in the
same document.  And if they're in the same document, then
they get to share content in all the delicious ways that
Mallard allows.

Obviously, you need to put a lot of thought into how your
document is organized.  And maybe you do some user testing
and find that the optimal organization is something that
Mallard doesn't have linking mechanisms for.  That's cool.
That means we have something to improve upon.  This would
be such a boring project if we got everything perfect on
the first iteration. ;-)

Where this becomes a more difficult issue is if you want
to transclude content between multiple documents.  I tend
to think that any content that's going to be plugged into
different documents needs to be written with that goal in
mind.  It needs to be very careful of what it links to
and what it assumes of the reader.

So maybe the best way to handle that is to put the content
we want to share into separate XML files, and if you want
to slurp it into your document, you write a wrapper page
file that pulls it in with XInclude.  That would allow
the payload to be generic, while giving you control over
how it links into your document.

> > That said, the modular document structure of Mallard makes remixing
> > far more feasible than with a book-structured format like DocBook.
> > We can make this happen.  But what I need is for the writers who
> > want this stuff to talk to me.
> >
> > (I've been wanting to put a site up on projectmallard.org where
> > people can host their own extensions, so we can all experiment
> > and see what everybody else is experimenting on.  If any web
> > developer types want to help, that would be awesome.)
> >
> >   
> >>  * converted into multiple delivery formats (x/html, pdf, etc.) (at 
> >> build time... ?)
> >>     
> >
> > To what end?  I'm not trying to say there's no reason to convert
> > to other formats, but you should have a user goal in mind when
> > you decide how to go about doing it.  Users are, by and large,
> > far less interested in documentation than you might think.
> >
> >   
> I tend to think (read: 'opinion' ;) that content viewed on the system 
> should be html files whose styling is controlled by css rather than 
> docbook that is transformed in real time. This is very flexible and 
> well-known and opens the door to a wide ocean of help viewers, while is 
> also probably faster (no run-time xslt). As I mentioned previously in 
> this chain, I wrote a webkit based viewer and xslt transforms (that run 
> at doc build time) that convert docbook articles into html (that part is 
> nwalsh) with css classes and javascript inserted (that's what my 
> transforms do) as needed. The webkit help viewer listens to gtk theme 
> change signals and simply rewrites the css file with new colors and 
> reloads the page to pick up the new theme colors. The result provides a 
> look and feel that is very similar to gnome user manuals now: forward 
> and back buttons, autogenerated  toc content on right as clickable links 
> (two levels deep), About this Doc info, etc. It is preliminary but is 
> meant to be a proof of concept that html&css based files can provided 
> the same user experience from docbook source, without run-time xslt 
> transforms and with dynamic responsiveness to the current theme.

Well, good, I'm glad you have code to back you up.  I get
the "let's just do HTML" or "let's just do PDF" argument
from time to time, but it's usually from people who don't
understand the run-time display issues and haven't written
a lick of code.

>  Again, 
> this is not meant to be a proposal, but to share some work I've done 
> with the community.  (Consider that  if the  help viewer is truly an 
> html browser, one could include links to online content  (like more 
> trouble shooting info, how to participate, translate, etc.,  *in the 
> same  viewer*.)

Yelp is perfectly capable of displaying HTML.  The fact that
it opens a web browser for http links is a design decision.
I don't want to write a web browser.  (That said, I think
there are cases where it would be nice to pull content from
the web to display in the help viewer, but I don't want to
use the help viewer as an arbitrary web browser.)

I don't want to tell you not to experiment with things.  That's
what makes free software tick.  But build-time or install-time
transformed documentation is not something I'm particularly
interested in pursuing upstream.

(On the other hand, there's a ton of awesome things I'd love
to pursue if I had more developers.  So if you're one of those
rare people who enjoys programming and documentation, I could
really use the help.)

--
Shaun