Developing Yelp [was Re: From the docteam meeting]

[Andreas Lloyd]

Don Scorgie wrote:
> Yes, I am subscribed and even occasionally read the list ;)
>
>   

Hi Don, thanks for the input! :-)

>> 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 :)
>
>   
Cool! I guess we should note that somewhere. I'll try a few test
searches to see what pops up.


> Andreas Lloyd wrote:
>> 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
>>     
>
> I'm not sure about the linking on the toolbar (if I read the spec
> correctly).  

You did. I wasn't very happy with it, but it is more the general idea of
enabling the user to easily send in errata that is important, rather
than where or how the linking works. I just wanted it to be big and visible.

> 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).  
Yeah, I considered that too - but seriously, who would ever look in the
Help menu of the Help application? I wanted something more spectacular.. ;-)

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

Yeah, again I didn't feel entirely confident that I was going about this
in the right way when I wrote this spec. I did notice the Mallard
project pages, but since there was no indication of whether actual work
is being done on it, I decided to try for the DocBook format anyway.
Having read the discussion about, I agree that Mallard's topic-based
format will be much better for Help docs. In the mean time, we'll have
to improvise something for the Ubuntu docs..


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

By the way,  I didn't think the tool bar that cluttered. I was imagining
the button at the far right of the toolbar, so that it wouldn't get in
the way of the other functions yet was easily visible.

I suppose that a short-term solution (until Yelp will be all glittering
Mallard goodness) would be to add something to the coming DocBook export
function that adds an extra line at the bottom of each exported page
with the text "Does this work for you? Share your experiences, tips and
tricks and improve the Ubuntu documentation" with a link to original
exported page. That should be doable. I suppose that is something I
should get that Summer of Code student to look at, instead.

Cheers,
Andreas

-- 
https://launchpad.net/people/lloydinho