Software Store Help (and Help Strategy)

[Matthew Paul Thomas]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

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.

I've reported a bug <http://launchpad.net/bugs/439353> on making the
Ubuntu Software Center help localizable. 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.

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.

> 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.

>...
> 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:

1.  No interactivity -- you can't even embed a "Show Me Where" button,
    let alone a "Show Me How" button. That's even worse than paper-based
    help (because on paper you can at least use screenshots without
    risking confusion).

2.  No context awareness -- I can't write, for example, <if
    environment="KDE">...<else>...</else></if>, or <if isinstalled=
    "aptoncd">...</if>.

3.  It's simpler than DocBook, but not nearly simple enough to be
    worth its inconsistency with HTML (as opposed to, for example, wiki
    syntax or Markdown). For example, what is the point of having <link
    xref> and <link href> instead of just <a href>?

4.  It repeats some of DocBook's annoying content model -- for example,
    the contents of a table cell has to be a block element, which is
    hardly ever appropriate in a help page.

5.  It's XML. This would make sense if XML5 was anywhere near
    standardization, but in XML's current state, the slightest syntax or
    packaging mistake will leave an already-stressed user looking at an
    error message instead of a help page.

Cheers
- --
Matthew Paul Thomas
http://mpt.net.nz/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkrJwa8ACgkQ6PUxNfU6ecpVMQCgzgW5cOYq9B/h800hVhFNBeSu
+PEAnAqnxEMqEkIQRNx6eiUrGzu4O0U2
=cnNE
-----END PGP SIGNATURE-----