Software Store Help (and Help Strategy)

[Matthew East]

Hi Kyle,

On Wed, Sep 30, 2009 at 4:37 PM, Kyle Nitzsche
<kyle.nitzsche at canonical.com> wrote:
> It seems reasonable though to expect that there will be other (maybe many)
> packages like this one (Software Center) that Canonical creates for karmic
> +n. I think that creating monolithic help (one package that contains
> everything) that's hard to customize (home page content is hard coded into
> yelp now) may not be the best approach down the road. Nor is copying the
> whole thing then modifying it the best approach either, I think, for various
> reasons, not least that it implies all customization has to happen *later*
> and that it involves massive source redundancy just to accomplish very minor
> modifications.

I do agree with these sentiments. There are already plenty of packages
like this (jockey, usb-creator) where we currently put the help in
ubuntu-docs. It clearly isn't the ideal approach, but I do think that
alternative approaches are inferior at the moment.

> If the documentation/translation tool chain and work flow needs modification
> to support a modified approach, that is not, I think, an insurmountable
> obstacle. The benefits of thinking seriously about this seem many, to me.
> The consequences of not doing it loom. (I am quite willing to help out.) I
> am not saying let's have change for the sake of change.

Yes, I'm definitely willing and interested in improving the situation
for the future and working on a solution. It's good to have your input
as someone working on a "downstream" product affected by these issues.

> I am wondering what Ubuntu Docs thinking is on Mallard. As you probably have
> noticed, I have a couple of predispositions that seem to be somewhat in
> contrast to the Mallard approach (even, alas, to the current Ubuntu
> approach):
> * Run-time transformation slow things down and is unnecessary: help should
> be installed as html files to keep things as flexible as possible in every
> dimension. Html can be dynamically themed (here's a prototype:
> http://people.canonical.com/~knitzsche/help_viewer/help-viewer.html)
> * Help development is free to be in any appropriate source file format
> (docbook, xml with xinclude, maybe even Mallard), as long as it can be
> transformed to the required delivery formats at build time (html, pdf are
> already solved).
> * Help viewer should not have the content built into it in any sense (should
> be able to switch the viewer without sacrificing content). (Yelp currently
> hard codes the Ubuntu Help Center home page content and translations.
> Mallard content seems to require the Yelp viewer.)
>
> Mallard, as awesome as it appears to be, is not a standard and seems to
> *require* yelp as the help viewer. This has numerous direct consequences. If
> work is undertaken to, for example, convert Ubuntu Docs to Mallard, it would
> be difficult to reconsider. Thus, it seems that a decision point is clearly
> approaching.

I'm not sure that there will be a decision to be made - the reality is
that with Gnome as our upstream, if we want to improve the help system
from where it is now, we are going to have to embrace the work that is
done upstream and use it to our advantage. We *could* continue with
the approach we have now, which is to customise the help centre and
provide our own documents which make it up, but the reality is that
the work on Mallard that is being done is being done partly to help
downstreams like ourselves improve the use made of upstream documents,
and improve the structure and style of the help generally. The whole
aim is to improve pluggability so that downstreams can integrate help
better with upstream work.

Mallard won't become default in Lucid, but it's likely to be
relatively close. I think that this is a good opportunity to provide
input to it while it is in the design stage, in order to make sure
that it works as well as possible for us. Phil is already doing a good
job there by working with upstream.

I can see that you do have some ideological differences which might
make you distrust Mallard, but again, I think we are going to have to
work with what we are given by upstream, and it will definitely be a
big improvement to what we have now.

BTW I don't think Mallard requires yelp as the help viewer - there
have been discussions about how XFCE and KDE could use it too,
although I don't know where those have got to. Equally, I don't think
that Mallard will involve hard-coding the help frontpage.

> Who from Ubuntu Docs is going to UDS? (I am.) I would enjoy
> meeting/discussing/learning.

Not me I'm afraid. However if you are ever in London...

-- 
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF