From the docteam meeting

[Don Scorgie]

Hi,

On Tue, 2006-07-25 at 02:35 +1200, Matthew Paul Thomas wrote: 
> On Jul 25, 2006, at 2:07 AM, Andreas Lloyd wrote:
> >
> > Matthew Paul Thomas wrote:
> >>
> >> To abolish the "Online Documentation" menu item, I've reported a bug
> >> on linking from Yelp search results to help.ubuntu.com search 
> >> results. <http://bugzilla.gnome.org/show_bug.cgi?id=344843> Once 
> >> that's implemented, the separate menu item will no longer be 
> >> necessary (and we'll start getting constant feedback, from search 
> >> logs, of what is missing or unfindable in our help).
> >
> > Yes! Brilliant! Have you had any response from the Yelp developers? As
> > far I can tell, they are Don Scorgie and Brent Smith. Don, I think, 
> > has been known to read this list from time to time.

Yes, I am subscribed and even occasionally read the list ;)

> 
> Don has been doing brilliant, and even more important, work on fixing 
> Yelp's search function, and I haven't dared distract him. :-)
> <http://bugzilla.gnome.org/show_bug.cgi?id=341434>
> <http://bugzilla.gnome.org/show_bug.cgi?id=341800>
> <http://bugzilla.gnome.org/show_bug.cgi?id=341797>

Thanks :)  Feel free to poke me about things.  I tend to forget about
them.

> 
> Now that those are fixed, bug 344843 is #1 on my wishlist.

I've just implemented this now.  As the bottom of any search results
there should now be a "Repeat this search online at GNOME Support
Forums", with a link to the relevant search.  Should be simple to change
it for distro specific stuff (only 3 string need changing at the top of
the file).

Any feedback from search results would be most appreciated :)

Andreas Lloyd wrote:
> Matthew Paul Thomas wrote:
> > Don has been doing brilliant, and even more important, work on
> fixing
> > Yelp's search function, and I haven't dared distract him. :-)
> > <http://bugzilla.gnome.org/show_bug.cgi?id=341434>
> > <http://bugzilla.gnome.org/show_bug.cgi?id=341800>
> > <http://bugzilla.gnome.org/show_bug.cgi?id=341797>
> >
> > Now that those are fixed, bug 344843 is #1 on my wishlist.
> 
> That is some really good work! I added the spec on a Contribute button
> in Yelp to the GNOME wiki and as a wishlist bug:
> 
> 
> http://live.gnome.org/Yelp/Yelp2Wiki
> http://bugzilla.gnome.org/show_bug.cgi?id=348542
> 
> Hopefully, it'll be possible to have both bug 344843 and bug 348542
> implemented. I'm not entirely happy with the spec yet, so feel free to
> add to it if you have some good ideas to improve on the design.

I'm not sure about the linking on the toolbar (if I read the spec
correctly).  On the main Yelp wiki page, there is a suggestion buried
deep down in the "For dreamers" section with something like this.  Its
only a single thought : "Submit document errata to bugzilla".  I thought
it was more fleshed out, but apparently not.

I mused on this a long while ago and came up with the following
proposal:
In the "Help" menu, a new entry entitled "Report a bug" (or similar),
which would fire up bug-buddy with most of the fields filled in (from
which manual someone was viewing).  Unfortunately, this would require
some fairly dramatic changes.  These changes are (or should be) part of
Project Mallard.
</distraction>

The proposal as it stands, I'm not sure about.  For 1, the toolbar is
already pretty cluttered in Yelp (for what it does).  There are Back and
forward buttons (now with drop-down menus), a "Home" button and a search
box.

For 2, there is much momentum being gained for the shift to Mallard.
This is a new doc format that is more topic-based.  The language that is
going to be used isn't docbook.  The tools will have to be able to cope
with this. [1]

For 3, not all documents in yelp are docbook.  The TOC, HTML and man /
info pages are all there.  If a new person spots an error in one of
these and they click the "Contribute" button, expecting to get to an
online editable version of the doc, where will they end up?

The idea itself is good, but I think more work may be needed before it's
considered.  It really needs to be pretty un-intrusive (as generally,
people want to find documentation, not edit the documentation), but
fairly easily discoverable.  I don't know the best solution.

Don

[1] Yes, there has been a long discussion about this on the gnome doc
mailing list:
http://mail.gnome.org/archives/gnome-doc-list/2006-July/msg00052.html

http://mail.gnome.org/archives/gnome-doc-list/2006-July/msg00053.html
gives an overview of the reasons for the switch