Software Store Help (and Help Strategy)

[Matthew East]

On Mon, Oct 5, 2009 at 10:51 AM, Matthew Paul Thomas <mpt at canonical.com> wrote:
> Last week I discussed this issue with Danilo Šegan (Launchpad
> Translations developer, and author of xml2po). He showed me how to
> convert the Ubuntu Software Center's DocBook help file to a PO file and
> back again, and I said it would be very cool if this could be automated
> in Launchpad Translations.

{snip}

> Whenever I remember, I will
> also nag the Translations team to automate this for all packages that
> contain DocBook files, and I suggest the Documentation Team remind them
> frequently too.

That would indeed be awesome. Launchpad already contains a feature for
automatic importing/exporting of pot and po files which can be used
for help. This feature only exists in upstream projects at the moment,
so ubuntu-docs doesn't use it (as we use the Ubuntu project for
translations).

The extra step needed is the transformation of the po files into xml
(we use xml2po, although there are other tools). For ubuntu-docs, this
is done at package build time. However, before doing it we need to
review and fix translations, because unfortunately due to the nature
of xml translations there are frequently errors unintentionally
introduced into the po files by translators (broken tags, certain tags
translated when they should be left in English, etc). This is an
exercise we routinely carry out for ubuntu-docs, but it would become
quite a serious burden to do it for multiple packages. If the
application developers are prepared to do the work, then that is fine,
but until some error checking is available directly in Launchpad, that
was the main reason that I wanted to keep the material in ubuntu-docs.

FWIW, the add-applications help has been updated to work with
software-center now and is found at ghelp:add-applications.

> Kyle Nitzsche wrote on 30/09/09 16:37:
>>...
>> 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)?
>
> In the Center help I already had to write a paragraph of the form "If
> you are using Ubuntu Netbook Remix...", which people using standard
> Ubuntu should never have to see. One way of fixing this would be to have
> separate branches of software-center for Ubuntu standard and UNR.
> Probably a better way would be to have an if-else block in the help file
> (if running UNR, show this paragraph, else show this paragraph), but
> neither DocBook nor Mallard seem to allow this.

This would be a good feature. I think that an alternative way of doing
it which will be supported in Mallard is the ability for a remix
distribution to add files which will take precedence over existing
installed files. That would mean that the remix developers could
customise the documentation relatively easily without having to ask
the original distribution developers or documentation team to do the
work themselves. I suppose that which approach is taken could depend
on how close the remix is to the original distribution, and how
closely the developers or documentation team collaborate.

>> 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.
>
> I don't understand why this would have a separate tab. Translations for
> help belong in "Translations", just like translations for anything else
> (such as package descriptions). And original help source belongs in
> Code; for example, the various "Help" buttons in a program's interface
> need to be able to rely on their target help pages existing.

Agreed. I think what Kyle was thinking about may be more that
Launchpad could provide a way to deliver help to end-users, rather
than necessarily manage the development of that help. I think the two
types of ideas should be kept distinct.

>> 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):
>>...
>
> I'm not a member of the Documentation Team, but from a quick browse of
> the draft specification (hopefully I've missed something!), the main
> problems with Mallard seem to be:

{snipped}

I'll pass this feedback to the upstream team working on Mallard. Some
of the points (but not all) seem to be issues that could be addressed.
Feedback is definitely useful because (aiui) Mallard is still work in
progress.


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