Software Store Help (and Help Strategy)

[Milo Casagrande]

Hi Kyle,

2009/9/30 Kyle Nitzsche <kyle.nitzsche at canonical.com>:
> Are you going to be at UDS?

I don't know, yet, if I'll be able to make it.

> If so, perhaps that would be a good chance to discuss/refine/define things
> as part of the process for getting a good blueprint together.

Yes, indeed. I would like if possible to start the blueprint before
the UDS from this discussion, but meeting and discussing in person is
totally different.

> As a starting point, how about:
> * the basic idea is that a source package may contain its own help (probably
> packaged in a standard way to facilitate LP integration, translation, etc.)

Yes, right now there are packages (few of them though) that ship their
documentation/help in a different directory than usual. That's
something that should be documented too.

> * Each package should/can have a "Help" (or "Documentation") tab in LP

IMHO, I think "help" could be misleading: people might think of it as
Launchpad help...

> * In that tab, one might set the Permissions (Open, Assigned, Closed, ...)
> * And widgets to assign the package to a Documentation Group (say, "Ubuntu
> Docs") (much like one now assigns a package's translations to Ubuntu
> Translators)

Yes, like the management interface for translations: simple and efficient.

> * Perhaps show some status, for example: "Help is Under Development" (which
> means feel free to change the source), or "Help is Frozen for String Freeze"
> etc.

This would be awesome for translations too! :)
Maybe even an "automatic" announce when you enter string freeze...

> * Documentation groups could get an LP page that automatically lists the
> packages assigned to them (like Ubuntu Translators does, although I can't
> find that at the moment :)

This one probably:

https://translations.launchpad.net/+groups/ubuntu-translators

at the end of the page.

> * Naturally, there would be a documentation group for Ubuntu: Ubuntu
> Documenters (or something).
> ( * There might be language specific teams: not for *translation*, but for
> screen shots ? )

I think screen shots localization should be done within a translation
team. There could be an upload interface to upload the screen shots.
At least right now documentation screens shots have always been done
by translation teams.

There should be a preview of the screen shots though: original and
localized (something like GNOME has).

> Questions/thoughts:
> * would help translations be delivered by the package or in language packs?
> Well, probably for Ubuntu, lang packs, but for upstream LP packages, by the
> package itself.

That's an interesting point. We've been talking a little bit about
this with the GNOME guys: why should I have the documentation
translation of an application I don't have installed?

I know it's the same approach that applications translations use right
now (you have all .mo files even of applications you don't install),
but shipping documentation all together takes up more space (screen
shots, XML file). It's a tricky part...

So, it's something that need to be discussed.

> * Thus, there should be a well-known toolchain to support extraction from
> source docbook (to start with) to po (xml2po anyone?), upload to LP (import
> translations from bzr branch?), and, after translation is complete, export
> to po in bzr branch. These imply a standard structure for help in a package,
> which may be new, but I don't think is  too hard.

There is also a check in the translate-toolkit [1] that will perform
XML tag consistency (it's kind of a basic check and can give false
positives, but better than nothing). Could be interesting to integrate
also that one into the toolchain, like a daily-hook that will check
consistency, maybe only during string freeze, if it's not possible to
do it on a per-page basis when you save your translation.

Ciao.

[1] http://translate.sourceforge.net/wiki/toolkit/index

-- 
Milo Casagrande <milo at casagrande.name>