possible documentation viewer?

[Sean Wheller]

On Saturday 04 June 2005 01:42, Jeff Waugh wrote:
> <quote who="Jeff Schering">
>
> > On 6/3/05, Jeff Waugh <jeff.waugh at ubuntu.com> wrote:
> > > Very little work has been done on option 1. I'll be using some of my
> > > desktop budget to deal with a number of Yelp issues, and will be paying
> > > attention to freedesktop.org movements in this area.
> >
> > Thanks! That's great. But please try to see how printing is a
> > showstopper. When a user asks "How do I print the help page?", the wrong
> > answer is "You don't need to print."
>
> That's very different from saying it's not a showstopper.

Jeff, please understand that I am not pointing at you personally here. What 
follows in a general statement of concern in the way @ubuntu.com people 
interact with the docteam.

It concerns me that people working for ubuntu seem to come and go from our 
forum and just drop in, pickup pieces, make comment and then expect the whole 
team to follow what they are saying. Then when the team disagrees, the motion 
is lost when the @ubuntu.com people just disappear.

There seems to be little regard for the intelligence of people in the docteam. 
This is the third or fourth such case where, as a docteam, people have 
discussed issues and problems at length and tried to resolve the problems. 
Failing to get support from developers, who we need, in order to improve 
applications, the team generally had to find alternative solutions. Wanting 
to move forward, they do, then in comes a developer and shines down in all 
glory and might to say, "You guys know nothing. You are straying from the 
flock, kneel, repent and follow my way."

The result is less than desirable, as it generally sounds like the developer 
is not actually prepared to listen and understand the needs of the authors or 
the users. It send disarray into our plans and generally demotivates those 
people who are focusing on doing commits to svn.

A while back on IRC I got to the point where I said that I would not be 
listening to anymore talk about application level solutions. That I will be 
focused on working with people who commit to the docs svn. At the time I had, 
had enough of the disruption brought in by debating what to do with the 
application layer. I have entered into this discussion because it finally 
seems that somebody in development is about to take the application layer 
seriously. I am happy if this is the case. However, I am also reserved on 
this, fearing lots of talk and no action that would result in the docteam 
again changing tack and then being left with nowhere to go as the developers 
fail to remain consistent on the help application layer.

Therefore, I will be following development in yelp but will not be changing 
the current direction of our development to match the limited functionality 
set of yelp. This does not mean that yelp will not oneday be able to 
dynamically transform our docbook. Our docbook is based on standard and the 
processing methods we use are common to docbook. So this just means that yelp 
will have to work hard to support docbook and its processing methods. Unlike 
most project that have dumbed down their docbook to work in yelp, we are 
saying, no, please make yelp a proper docbook compliant tool. The challenge 
is, IMHO always was, for yelp to be a help viewer capable of reading and 
transforming valid and well-formed docbook xml. Somewhere, people have 
forgotten this, and yelp became restrictive. 

The fact that we currently want to transform to static HTML is not a situation 
that is a blocker to packaging it in the distro. Our requirements may not all 
be show stoppers, but are valid none-the-less. Disregarding them, is 
disregarding the good will and enthusiasm of the docteam to produce a great 
help system that users have asked for.

What we are doing is forcing challenging help viewer tools while remaining 
with the ability to deliver on our goals. Note that our goal is not to 
develop a yelp or kHelpcenter, but to deliver good documents and provide the 
electronic feature set users want and need in order to discover and use the 
information we provide. If we need to deliver this as HTML until such time as 
help tools have caught up, then we have done no harm to the users and made no 
problems for the developers and packagers.

Thanks for you time in this discussion. I am sure that everyone in the team 
greatly appreciates it and looks forward to seeing the rapid developments and 
improvements that will soon be released with yelp.

-- 
Sean Wheller
Technical Author
sean at inwords.co.za
084-854-9408
http://www.inwords.co.za
Registered Linux User #375355
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20050604/2195dc1e/attachment.pgp>