Re: modifying yelp

[Phil Bull <philbull gmail com>]

Hi Vikram,

Sorry for the delay in replying.

On Sun, 2010-06-27 at 02:22 -0400, Vikram Dhillon wrote:
[...]
> 1. I have been working with some people over at google, and we can use a script used made
> by Phil that analyzes what people are asking over IRC channels, and we
> can also give some keywords to the specific software/package we care
> for. Phil's script is in one of my branches :) and from google, if we
> ask them on nicely I am pretty sure they would let us use some analytics :) From 
> that information we can better focus on what the user needs.

I agree that we should be spending more time examining users' needs.
There's lots of data out there that could be really useful to us, if
only we had access to it! In particular, I'd love to see the webserver
log statistics for help.ubuntu.com and library.gnome.org. I think my IRC
script could be helpful too, but it runs out of steam for a lot of GNOME
apps (only returning a few entries for certain apps).

I wonder if we should talk to people who're used to supporting large
GNOME deployments? I'm sure info from their helpdesk system could prove
insightful too.

> 2. Documentation is good if we keep it updated, I have been playing around
> with yelp to implement some features with the same idea as rss so we
> can direct/send new information painlessly which would be sort of like a
> patch but will also help keep the docs. updated from time to time.

Updating docs is a difficult one. Distros typically want to be in
control of updates, and some package update policies for stable releases
(such as Ubuntu's) recommend against low-priority updates (which doc
updates would normally be classed as). It would be cool to have
something like the online help browsing feature that Microsoft use,
though.

Maybe we could pop-up a banner in Yelp saying "An updated version of
this topic is available", with a link through to library.gnome.org? All
you'd need to do is keep a list of updated topics and the URL for the
updated page in a text file somewhere online. This method would have the
advantage of not installing updated docs itself (which the distros would
probably hate), while still being easy for users to handle. (Obviously,
in a perfect world, we'd just download the topic for them.)

> 3. The most important one, we NEED a online system like google sidewiki
> where users can go and comment on what they liked on the page they were
> reading, or something rather inside yelp again that users can use to
> send through comments, google's sidewiki has an awesome spam protection
> algorithm that we can also use. This connects us directly to the users
> and combined with step one we can see what the users are looking for the
> most and send them this information.

That sounds good; getting user feedback would be really useful. For now,
I think a basic "star rating" system would suffice. Sifting through
comments and converting them to bugs is a thankless task, and users are
likely to be frustrated if we don't listen to their comments and take
action. Keeping it simple for now would give us some insight while not
generating a massive workload.

> 4. A last step would be to write a script that automatically convert
> wiki pages to docbook markup, something like that already exists in
> gnome, I remember seeing an email conversation on that topic so I'll
> pull that script and see how we can use it here

We're using Mallard rather than DocBook now. I'm not very keen on
writing docs through the wiki because you lose a lot of the sense of the
structure of the document as a whole, and there's a tendency for topics
to get long and complicated. Version control is more difficult too.

Thanks for looking at all these issues, Vikram! I really appreciate your
enthusiasm, and I think that some of these ideas will help us to produce
really great docs for our users.

Phil

-- 
Phil Bull
https://launchpad.net/~philbull