Software Store Help (and Help Strategy)

[Kyle Nitzsche]

Hi Matthew and all,

It's late in the karmic cycle, so my two cents is definitely go ahead 
with whatever approach works best for the Software Center help.

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.

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.

Please bear in mind that we are not just talking about Ubuntu and Ubuntu 
Netbook Remix, but also the recently announced the Ubuntu Moblin Remix 
(UMR). This may become a standard Ubuntu remix, just like UNR has become 
one. I can imagine that UMR would want mostly standard content (perhaps 
Software Center, perhaps usb-creator, networking, etc.), but would need 
it to be customized (the home page might be somewhat different, maybe 
different text and some new/replacement/dropped topics). How many other 
standard remixes of Ubuntu will there be, each of which may need 
customized help (home page plus topic remixing)?

As a quick thought: LP now provides a structure (pages/work flow) that 
assists Ubuntu Translators with keeping track of the different packages 
they need to work on for each release. Maybe something similar could be 
created for help (docs)? Maybe, just as there is a "Translations" tab 
for each package, there can/should be a "Help" tab, with a 
structured/manageable relationship (in LP) to translations?. (I know, 
call me crazy ; ) With this, each package could deliver its own 
(translated) help, facilitated by LP.

Creating a doc remix (even Ubuntu becomes a "remix") would entail;
 * creating the home page content (translated) and installing it in the 
location the help viewer requires
 * that home page simply has links to whatever content is appropriate 
for the remix

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.

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

Cheers,
Kyle

Matthew East wrote:
>> On Fri, Sep 25, 2009 at 7:38 PM, Kyle Nitzsche
>> <kyle.nitzsche at canonical.com> wrote:
>>     
>>> In the mean time, I propose this app's help content should be kept separate
>>> and should be launched from within the package, to ensure it is actually
>>> present on all systems.
>>>       
>
> Sorry I also had a question about this which I missed out in my email.
> Part of the proposal is for the application to depend on ubuntu-docs,
> so that its help would indeed be present on all systems. The
> application's help button would call the relevant document in
> ubuntu-docs, without affecting any yelp customisations that you do.
> Does that create specific problems for you?
>
>